はじめに
Databricks AppsからAgent Bricksを経由して外部サービス (Salesforce, Slack等) を呼び出す構成を検討する際、外部サービス側でもユーザー単位の認証が必要なケースがあります。
本記事では、この要件を満たすための認証構成の選択肢を整理し、それぞれのPros/Consを解説します。
前提知識: 外部サービス認証の3つの方式
外部サービス (Salesforce, Slack等) を呼び出す際の認証方式には、主に以下の3つがあります。
Bearer Token
最もシンプルな認証方式です。
- 外部サービスから発行された固定のトークン文字列をリクエストヘッダーに含めて送信
- トークンが有効な間はアクセスが許可される
- トークンの有効期限や更新は外部サービスの仕様に依存
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
特徴:
- 設定がシンプル
- トークンを知っている人は誰でも同じ権限でアクセス可能
- トークンの漏洩リスクに注意が必要
OAuth Machine-to-Machine (M2M)
システム間通信向けの認証方式です。
Salesforce: 「誰ですか？」
エージェント: 「Databricksシステムです (client_id: xxx, client_secret: yyy)」
Salesforce: 「OK、システムに許可された全データを見せますね」
- Client IDとClient Secretを使って、システム (アプリケーション) として認証
- ユーザーの介在なしに自動でトークンを取得・更新
- 誰がアプリを使っていても、外部サービス側から見ると同じ「システムアカウント」
特徴:
- ユーザーごとのログイン操作が不要
- 自動化やバッチ処理に適している
- 外部サービス側でユーザー単位のアクセス制御はできない
OAuth User-to-Machine Per User (U2M Per User)
ユーザー単位の認証方式です。
Salesforce: 「誰ですか？」
エージェント: 「田中さんの代理です (田中さんが認証済み)」
Salesforce: 「OK、田中さんが見れるデータだけ見せますね」
- 各ユーザーが初回アクセス時にOAuth認証画面でログイン
- ユーザーごとに個別のアクセストークンが発行される
- 外部サービス側でユーザー単位のアクセス制御が効く
特徴:
- ユーザーごとのデータアクセス制限が可能
- 監査ログに「誰がアクセスしたか」が記録される
- 各ユーザーが初回に認証操作を行う必要がある
3つの方式の比較
| 項目 | Bearer Token | OAuth M2M | OAuth U2M Per User |
|---|---|---|---|
| 認証主体 | トークン保持者 | システム | 個別ユーザー |
| 初回セットアップ | トークン設定のみ | Client ID/Secret設定 | 各ユーザーがログイン |
| トークン更新 | 手動 or サービス依存 | 自動 | 自動 |
| ユーザー単位のアクセス制御 | ❌ | ❌ | ✅ |
| 監査ログのユーザー識別 | ❌ | ❌ | ✅ |
| 適したユースケース | 簡易な連携 | バッチ処理、自動化 | ユーザー権限が重要な業務アプリ |
構成の選択肢
選択肢A: Apps → Agent Bricks → 外部サービス
┌──────────┐ ┌──────────────┐ ┌────────────┐
│ Apps │ → │ Agent Bricks │ → │ 外部サービス │
└──────────┘ └──────────────┘ └────────────┘
Agent Bricksを使用する構成です。ノーコードでエージェントを構築できます。
選択肢B: Apps → Agent Framework → 外部サービス
┌──────────┐ ┌─────────────────┐ ┌────────────┐
│ Apps │ → │ Agent Framework │ → │ 外部サービス │
└──────────┘ └─────────────────┘ └────────────┘
Agent Frameworkでカスタムエージェントを構築する構成です。コードでの実装が必要です。
選択肢の比較
| 項目 | Agent Bricks | Agent Framework |
|---|---|---|
| 作り方 | UIでポチポチ | コードで実装 |
| 難易度 | 低い | 高い |
| 外部サービス認証 | Bearer Token / M2M のみ | U2M Per User も可 |
| ユーザー単位認証 | ❌ できない | ✅ できる |
選択肢Aの制限事項
Agent Bricksでは外部サービスへのOAuth U2M Per User認証ができません。
この制限により、以下の要件には選択肢Aでは対応できません:
-
外部サービス側でユーザーごとのアクセス制御が必要な場合
- 例: 「Salesforceで田中さんは自分の担当顧客データのみ閲覧可能」といった制御
-
外部サービス側で誰がアクセスしたか監査ログを残したい場合
- 例: 「Slackへの投稿が誰の名義で行われたか記録したい」
-
外部サービスのライセンスがユーザー単位で管理されている場合
- 例: 「各ユーザーが自分のAPIクォータを消費する必要がある」
これらの要件がある場合は、選択肢B (Agent Framework) を選択してください。
登場するコンポーネント
全体像
┌─────────────────────────────────────────────────────────────┐
│ Databricks Apps │
│ │
│ 認証: Service Principal または User Authorization │
└──────────────────────────┬──────────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ Agent Bricks │ │ Agent Framework │
│ (ノーコード) │ │ (コードで自作) │
│ │ │ │
│ 外部接続: │ │ 外部接続: │
│ ・Bearer Token │ │ ・Bearer Token │
│ ・OAuth M2M │ │ ・OAuth M2M │
│ │ │ ・OAuth U2M Per User│
└──────────┬──────────┘ └──────────┬──────────┘
│ │
└───────────────┬───────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ Unity Catalog Connection │
│ │
│ 外部サービスの「住所」と「鍵」を安全に保管 │
└──────────────────────────┬──────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ 外部サービス │
│ (Salesforce, Slack 等) │
└─────────────────────────────────────────────────────────────┘
Databricks Apps
ユーザーが触るフロントエンド (Streamlit, Gradio等) です。
認証の選択肢:
| 選択肢 | 説明 |
|---|---|
| Service Principal | 全ユーザーが同じ権限で動作 |
| User Authorization | ユーザー本人の権限で動作 |
Agent Bricks
UIでエージェントを構築できるマネージドサービスです。
Multi-Agent Supervisorに追加できるサブエージェント:
- Genie Space
- Knowledge Assistant エンドポイント
- Unity Catalog 関数
- 外部 MCP サーバー (Connection 経由)
外部サービス認証の選択肢:
| 選択肢 | 説明 | サポート |
|---|---|---|
| Bearer Token | 固定トークンで接続 | ✅ |
| OAuth M2M | システムアカウントで接続 | ✅ |
| OAuth U2M Per User | ユーザーごとに個別接続 | ❌ |
Agent Framework
コードでカスタムエージェントを構築するフレームワークです。
外部サービス認証の選択肢:
| 選択肢 | 説明 | サポート |
|---|---|---|
| Bearer Token | 固定トークンで接続 | ✅ |
| OAuth M2M | システムアカウントで接続 | ✅ |
| OAuth U2M Per User | ユーザーごとに個別接続 | ✅ |
Unity Catalog Connection
外部サービスへの接続情報 (URL、認証情報) を安全に保管する箱です。
Agent BricksでもAgent Frameworkでも、外部サービスを呼ぶ場合は必須です。
U2M Per User の場合のトークン管理
OAuth U2M Per User を使用する場合、Unity Catalogが各ユーザーのトークンを管理します。
- 初回認証: 各ユーザーは初めてConnectionを使う際にOAuth認証画面にリダイレクトされ、自分の認証情報でログイン
- トークン保管: 取得したアクセストークン/リフレッシュトークンはUnity Catalogが安全に保管
- トークン更新: Unity Catalogがリフレッシュトークンを使って自動的にアクセストークンを更新
つまり、アプリ側でトークンを管理するコードを書く必要はなく、Unity Catalog Connectionを呼び出すだけで、適切なユーザーのトークンが自動的に使用されます。
選択肢A: Agent Bricksを使う場合
構成図
┌──────────┐ ┌──────────────────────────┐ ┌────────────┐
│ Apps │ → │ Agent Bricks │ → │ 外部サービス │
│ │ │ Multi-Agent Supervisor │ │ │
└──────────┘ └──────────────────────────┘ └────────────┘
│
▼
┌─────────────────┐
│ Connection │
│ (Bearer/M2M) │
└─────────────────┘
設定手順
Step 1: Connection を作成
Catalog Explorerで外部サービスへの接続情報を登録します。
| 項目 | 設定例 |
|---|---|
| 名前 | slack_connection |
| タイプ | HTTP |
| ホスト | slack.com |
| 認証 | Bearer Token |
| Is MCP connection | ✅ チェック |
重要: 「Is MCP connection」にチェックを入れることで、Agent Bricksから選択できるようになります。
Step 2: Agent Bricks Multi-Agent Supervisor で設定
- Agents > Multi-Agent Supervisor > Build に移動
- 「エージェントの構成」で「+ 追加」をクリック
- 種類: 「外部 MCP サーバー」を選択
- Unity Catalog 接続: 作成したConnectionを選択
- エージェント名と説明を入力
Step 3: Apps から呼び出し
AppsからはAgent Bricksのエンドポイントを呼ぶだけです。Connectionの存在を意識する必要はありません。
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ChatMessage, ChatMessageRole
client = WorkspaceClient()
response = client.serving_endpoints.query(
name="your-multi-agent-supervisor-endpoint",
messages=[
ChatMessage(
role=ChatMessageRole.USER,
content="チームに進捗を共有して"
)
]
)
Pros/Cons
Pros:
- UIでポチポチ設定するだけで構築可能
- コーディング不要
- 自動最適化機能あり
Cons:
- 外部サービスへのユーザー単位認証ができない (Bearer Token / OAuth M2M のみ)
- 全ユーザーが同じ認証情報で外部サービスにアクセスするため:
- 外部サービス側でユーザーごとのアクセス制御ができない
- 監査ログに個別ユーザーの記録が残らない
選択肢B: Agent Frameworkを使う場合
構成図
┌──────────┐ ┌─────────────────────────────┐ ┌────────────┐
│ Apps │ → │ Agent Framework │ → │ 外部サービス │
│ │ │ (カスタムエージェント) │ │ │
└──────────┘ └─────────────────────────────┘ └────────────┘
│
▼
┌─────────────────┐
│ Connection │
│ (U2M Per User) │
└─────────────────┘
UC Connectionは必須か?
Agent Frameworkでは、外部サービスへの接続方法として以下の2つの選択肢があります。
方法1: UC Connection経由 (推奨)
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod
WorkspaceClient().serving_endpoints.http_request(
conn="connection_name", # UC Connection
method=ExternalFunctionRequestHttpMethod.POST,
path="/api/v1/resource",
json={"key": "value"}
)
方法2: 手動認証 (UC Connection不要)
環境変数やDatabricks Secretsで認証情報を管理し、requestsライブラリ等で直接呼び出すことも可能です。
import requests
from databricks.sdk import dbutils
api_key = dbutils.secrets.get(scope="my-scope", key="api-key")
response = requests.post(
"https://api.example.com/v1/resource",
headers={"Authorization": f"Bearer {api_key}"},
json={"key": "value"}
)
比較
| 項目 | UC Connection | 手動認証 |
|---|---|---|
| 認証情報管理 | UCが安全に保管 | 自分でSecrets管理 |
| トークン更新 | 自動 | 自分で実装 |
| アクセス制御 | USE CONNECTION権限で管理 | 自分で管理 |
| U2M Per User | ✅ 対応 | ❌ 自前実装は困難 |
結論: UC Connectionは推奨されますが必須ではありません。ただし、U2M Per User認証を使いたい場合は、UC Connectionが実質的に必須です。OAuthトークンの取得・保管・更新を自前で実装するのは現実的ではないためです。
設定手順
Step 1: Connection を作成 (U2M Per User)
OAuth U2M Per User タイプのConnectionはUIでのOAuthフローが必要です。
- Catalog Explorer > External data > Connections に移動
- Create connection をクリック
- HTTP を選択
- Authentication で「OAuth User-to-Machine Per User」を選択
- OAuthフローを完了
Step 2: カスタムエージェントを実装
from mlflow.pyfunc import PythonModel
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod
from databricks_ai_bridge import ModelServingUserCredentials
class UserAuthAgent(PythonModel):
def predict(self, context, model_input):
# ユーザーの認証情報を使用
user_client = WorkspaceClient(
credentials_strategy=ModelServingUserCredentials()
)
# ユーザー権限で外部APIを呼び出し
response = user_client.serving_endpoints.http_request(
conn="your_u2m_connection", # U2M Per User Connection
method=ExternalFunctionRequestHttpMethod.GET,
path="/user-specific-endpoint"
)
return {"result": response}
注意: http_requestはPython SDK経由で呼び出す必要があります。SQL経由のhttp_requestはU2M Per User Connectionではブロックされます。
Step 3: Model Serving にデプロイ
import mlflow
with mlflow.start_run():
mlflow.pyfunc.log_model(
artifact_path="agent",
python_model=UserAuthAgent(),
pip_requirements=[
"mlflow>=2.22.1",
"databricks-sdk",
"databricks-ai-bridge"
]
)
Step 4: Apps から呼び出し
Agent Bricksと同様に、エンドポイントを呼ぶだけです。
Pros/Cons
Pros:
- 外部サービスへのユーザー単位認証が可能
- 各ユーザーの権限で外部サービスにアクセス
- 監査ログでユーザー単位の追跡が可能
Cons:
- コードでの実装が必要
- Agent Bricksの自動最適化機能が使えない
- 開発・保守コストが高い
判断フローチャート
外部サービスをユーザーごとに認証したい？
│
├─ No → 選択肢A: Agent Bricks を使う
│ シンプルで構築が楽
│
└─ Yes → 選択肢B: Agent Framework で自作
手間はかかるがユーザー単位認証が可能
まとめ
| 項目 | Agent Bricks | Agent Framework |
|---|---|---|
| 作り方 | UIでポチポチ | コードで実装 |
| 難易度 | 低い | 高い |
| 外部サービス認証 | Bearer/M2M のみ | U2M Per User も可 |
| ユーザー単位認証 | ❌ | ✅ |
| 使うべきケース | ユーザー単位認証が不要 | ユーザー単位認証が必要 |
外部サービスへのユーザー単位認証が必要な場合は、現時点ではAgent Frameworkでカスタムエージェントを構築する必要があります。
参考ドキュメント
- 外部 HTTP サービスに接続する (日本語) - Bearer Token、OAuth M2M、U2M Per Userの設定方法
- Agent Bricks: Multi-Agent Supervisor (日本語)
- 外部 MCP サーバーを使用する (日本語)
- AI エージェント ツールを外部サービスに接続する (日本語)
- Databricks Apps の認可を構成する (英語)
検証について
本記事の内容は、外部サービスとの実際の連携が必要なため、完全な検証が難しい部分があります。実際に構築される際は、以下の点にご注意ください。
- U2M Per User Connectionは各ユーザーが事前にOAuth認証を完了する必要がある
- 外部サービスがOAuth 2.0仕様に準拠している必要がある