メインコンテンツまでスキップ
に最終更新

エージェントの認証

エージェントは、タスクを完了するために他のリソースに対して認証を行う必要があることがよくあります。たとえば、デプロイされたエージェントは、非構造化データをクエリーするためにAI Searchインデックスへのアクセス、基盤モデルを呼び出すためのEndpoint、またはカスタムロジックを実行するためのUnity Catalog関数を必要とする場合があります。

このページでは、Databricks Appsにデプロイされたエージェントの認証方法について説明します。Model Serving Endpointにデプロイされたエージェントについては、エージェントの認証 (Model Serving)を参照してください。

Databricks Appsは、エージェント向けに2つの認証方法を提供しています。各メソッドは、異なるユースケースに対応しています。

手法

説明

いつ使用するか

アプリ認可

エージェントは、一貫したアクセス許可を持つ自動的に作成されたService Principalを使用して認証します。以前はService Principal認証と呼ばれていました。

最も一般的なユースケース。すべてのユーザーがリソースに同じアクセス権を持つ必要がある場合に使用します。

ユーザー認可

エージェントは、リクエストを行うユーザーのIDを使用して認証を行います。以前はOn-Behalf-Of (OBO) 認証と呼ばれていました。

ユーザー固有の権限、監査証跡、または Unity Catalog を使用したきめ細やかなアクセス制御が必要な場合に使用します。

手法

説明

いつ使用するか

アプリ認可

エージェントは、一貫したアクセス許可を持つ自動的に作成されたService Principalを使用して認証します。以前はService Principal認証と呼ばれていました。

最も一般的なユースケース。すべてのユーザーがリソースに同じアクセス権を持つ必要がある場合に使用します。

ユーザー認可

エージェントは、リクエストを行うユーザーのIDを使用して認証を行います。以前はOn-Behalf-Of (OBO) 認証と呼ばれていました。

ユーザー固有の権限、監査証跡、または Unity Catalog を使用したきめ細やかなアクセス制御が必要な場合に使用します。

両方の方法を単一のエージェントで組み合わせることができます。たとえば、アプリ認証を使用して共有AI Searchインデックスにアクセスしながら、ユーザー認証を使用してユーザー固有のテーブルをクエリします。

ワークスペースUIまたはDeclarative Automation Bundlesで認証を構成します​

すべての認証設定は、次の2つの方法で構成できます。

  • ワークスペース UI: 「構成」ステップからアプリを編集し、リソースとスコープを管理します。ワークスペースで単一のアプリを反復処理する場合に推奨されます。
  • 宣言型オートメーションバンドル ：リソース、スコープ、および環境変数をdatabricks.ymlファイルで宣言し、databricks bundle deployでデプロイします。Gitベースのバージョン管理、CI/CD、または同じエージェントをワークスペース間で展開する場合におすすめです。All agent Template ship with a databricks.yml.

どちらのパスも同じランタイム構成を生成します。このページの残りの部分では、各手順を両方の形式で示しているため、1つを選択してプロジェクト内で一貫性を保つことができます。

いずれかのパスを通じてアプリにリソースを追加するには、そのリソースとアプリの両方に対する Can Manage 権限が必要です。

完全なバンドル参照については、アプリリソースとapp.resourcesを参照してください。エンドツーエンドのバンドルのウォークスルーについては、宣言型オートメーションバンドルを使用したDatabricksアプリの管理を参照してください。

アプリの認可​

defaultでは、Databricks Apps はアプリの認可を使用して認証します。Databricks はアプリを作成すると自動的に Service Principal を作成し、それがアプリの ID として機能します。

アプリと対話するすべてのユーザーは、Service Principalに対して定義された同じ権限を共有します。このモデルは、すべてのユーザーに同じデータを表示させたい場合、またはアプリがユーザー固有のアクセス制御に縛られない共有操作を実行する場合に効果的に機能します。

アプリの承認に関する詳細情報は、アプリの承認を参照してください。

MLflowエクスペリメントにアクセス許可を付与します。​

エージェントは、トレースと評価結果をログに記録するためにMLflowエクスペリメントにアクセスする必要があります。Service Principalにエクスペリメントでの Can Edit 権限を付与します。

  1. アプリのホームページで、 編集 をクリックします。
  2. 構成 ステップに移動します。
  3. App リソース セクションで、Can Edit権限でMLflow エクスペリメント リソースを追加します。

「DatabricksアプリにMLflowエクスペリメントリソースを追加する」を参照してください。

他のDatabricksリソースへの権限を付与する​

エージェントがGenieエージェント、AI Searchインデックス、SQL Warehouseなどの他のDatabricksリソースを使用する場合、Service Principalにそれぞれに対するアクセス許可を付与してください。

プロンプトレジストリにアクセスするには、プロンプトを格納するためのUnity CatalogスキーマにCREATE FUNCTION、EXECUTE、およびMANAGEの権限を付与します。

Unity Catalog リソースへのアクセス権を付与する場合は、すべてのダウンストリームの依存リソースにもアクセス許可を付与する必要があります。例えば、Genie Agent へのアクセス権を付与する場合は、その基盤となるテーブル、SQL Warehouse、および Unity Catalog の関数へのアクセス権も付与する必要があります。

Databricksワークスペースでアプリを作成または編集するときに、**App resources**セクションからアプリにリソースを追加します。

  1. アプリのホームページで、 編集 をクリックします。
  2. 構成 ステップに移動します。
  3. App リソース で、エージェントが使用する各リソースの + リソースの追加 をクリックし、アクセス許可を設定します。

サポートされているリソースとスクリーンショットの完全なリストについては、Databricks アプリへのリソースの追加を参照してください。

次の表に、上記の例で使用されている最小限の権限と、各リソースタイプに対応する宣言型オートメーションバンドルの値を示します。

リソースタイプ

ワークスペース UI の権限

宣言型オートメーションバンドルのリソースとアクセス許可

SQLウェアハウス

Can Use

sql_warehouse と CAN_USE

モデルサービングエンドポイント

Can Query

serving_endpoint と CAN_QUERY

Unity Catalog 関数

Can Execute

uc_securable securable_type: FUNCTIONと EXECUTE

Genie Agent

Can Run

genie_space と CAN_RUN

AI Searchインデックス

Can Select

uc_securable securable_type: TABLEと SELECT

Unity Catalogテーブル

SELECT

uc_securable securable_type: TABLEと SELECT

Unity Catalog接続

Use Connection

uc_securable securable_type: CONNECTIONと USE_CONNECTION

Unity Catalogボリューム

Can Read または Can Read and Write

uc_securable securable_type: VOLUMEとREAD_VOLUME、または WRITE_VOLUME

Lakebase（プロビジョニング済み）

Can Connect and Create

database と CAN_CONNECT_AND_CREATE

Lakebase (オートスケーリング)

Can Connect and Create

postgres と CAN_CONNECT_AND_CREATE

リソースタイプ

ワークスペース UI の権限

宣言型オートメーションバンドルのリソースとアクセス許可

SQLウェアハウス

Can Use

sql_warehouse と CAN_USE

モデルサービングエンドポイント

Can Query

serving_endpoint と CAN_QUERY

Unity Catalog 関数

Can Execute

uc_securable securable_type: FUNCTIONと EXECUTE

Genie Agent

Can Run

genie_space と CAN_RUN

AI Searchインデックス

Can Select

uc_securable securable_type: TABLEと SELECT

Unity Catalogテーブル

SELECT

uc_securable securable_type: TABLEと SELECT

Unity Catalog接続

Use Connection

uc_securable securable_type: CONNECTIONと USE_CONNECTION

Unity Catalogボリューム

Can Read または Can Read and Write

uc_securable securable_type: VOLUMEとREAD_VOLUME、または WRITE_VOLUME

Lakebase（プロビジョニング済み）

Can Connect and Create

database と CAN_CONNECT_AND_CREATE

Lakebase (オートスケーリング)

Can Connect and Create

postgres と CAN_CONNECT_AND_CREATE

最小権限の原則に従います。Service Principal にはエージェントが必要とする権限のみを付与し、アプリごとに専用の Service Principal を使用してください。完全なリストについては、セキュリティのベストプラクティスを参照してください。

ユーザー認可​

備考

プレビュー

ユーザー認証はパブリックプレビュー段階です。ユーザー認証を使用する前に、ワークスペース管理者が有効にする必要があります。

ユーザー認可により、エージェントは要求を行うユーザーのIDで動作できます。これにより、次の機能が提供されます。

  • 機密データへのユーザーごとのアクセス
  • Unity Catalog によるきめ細かなデータ制御
  • ユーザー固有の監査証跡
  • 行レベルフィルターと列マスクの自動適用

エージェントが、アプリのService Principalではなく、要求元のユーザーのIDを使用してリソースにアクセスする必要がある場合は、ユーザー認証を使用します。

ユーザー認証の仕組み​

エージェントのユーザー承認を設定する場合:

  1. アプリに API スコープを追加する ：アプリがユーザーに代わってアクセスできる Databricks APIs を定義します。アプリにスコープを追加するを参照してください。
  2. ユーザー認証情報がダウンスコープされます : Databricks はユーザーの認証情報を受け取り、定義した API スコープのみに制限します。
  3. トークン転送 ：ダウンスコープされたトークンは、x-forwarded-access-token HTTPヘッダーを通じてアプリで利用できます。
  4. MLflow AgentServer がトークンを保存します : Agent Server は、エージェントコードから便利にアクセスできるように、リクエストごとにこのトークンを自動的に保存します。

アプリの作成時または編集時にDatabricks Apps UIでスコープを追加するか、APIを使用してプログラムで、ユーザー認証を構成します。詳細な手順については、アプリへのスコープの追加を参照してください。

ユーザー認証を持つエージェントは、以下のDatabricksリソースにアクセスできます:

  • SQLウェアハウス
  • Genie Agent
  • ファイルとディレクトリ
  • モデルサービングエンドポイント
  • AI Searchインデックス
  • Unity Catalog接続
  • Unity Catalogテーブル

ユーザー認証を実装します​

ユーザー認可を実装するには、アプリに認可スコープを追加する必要があります。スコープは、ユーザーに代わってアプリが実行できることを制限します。利用可能なスコープとスコープのセマンティクスの一覧については、スコープベースのセキュリティと権限昇格を参照してください。

  1. Databricks UIで、アプリの Authorization 設定に移動します。
  2. **ユーザー認可**で、**+スコープの追加**をクリックし、アプリがユーザーに代わってリソースにアクセスするために必要なスコープを選択します。
  3. 変更を保存してアプリを再起動します。

エージェントコードでユーザー認証を設定するには、AgentServerからこのリクエストのヘッダーを取得し、それらの資格情報を使用してワークスペースクライアントを構築します。

  1. エージェントコードで、認証ユーティリティをインポートします：

    databricks/app-templatesから提供されているTemplateのいずれかを使用する場合は、提供されているユーティリティをインポートしてください：

    Python
    from databricks_app.utils import get_user_workspace_client

    それ以外の場合は、エージェントサーバーのユーティリティからインポートしてください：

    Python
    from agent_server.utils import get_user_workspace_client

    get_user_workspace_client()関数はAgent Serverを使用してx-forwarded-access-tokenヘッダーをキャプチャし、これらのユーザー認証情報でワークスペースクライアントを構築して、ユーザー、アプリ、およびエージェントサーバー間の認証を処理します。

  2. ワークスペース クライアントは、アプリの Startup 時ではなく、クエリー時に初期化します：

重要

__init__またはアプリのStartup時ではなく、invokeおよびstreamハンドラー内でget_user_workspace_client()を呼び出します。ユーザーがリクエストを行う場合、ユーザー認証情報はクエリー時にのみ利用可能です。ユーザーコンテキストがまだ存在しないため、アプリのStartup中に初期化すると失敗します。

Python
# In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)

スコープの追加とスコープベースのセキュリティの理解に関する完全なガイドについては、「スコープベースのセキュリティと特権昇格」を参照してください。エージェントが必要とする最小限のスコープのみを要求し、ユーザーに代わって実行されたすべてのアクションをログに記録してください。「ユーザー認証のベストプラクティス」を参照してください。

ユーザー認可の確認​

スコープを追加してget_user_workspace_client()を呼び出した後、アプリのDatabricksサービスプリンシパルではなく、エージェント実行が呼び出し元であることを確認します。 転送されたトークンが見つからない場合、 get_user_workspace_client()発生せずにDatabricksサービス プリンシパルにフォールバックするため、エージェントはアプリとして動作しながら、通常の応答を返すことができます。 確認するには、 whoamiツールを追加し、自分自身としてそれを呼び出してください。ユーザー名が返された場合、ユーザー認証は正常に機能しています。

current_user.me() はdefault iam.current-user:readスコープでカバーされているため、このテストのためにスコープを追加する必要はありません。

Python
from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
    """Returns the identity of the current user."""
    user_wc = get_user_workspace_client()
    return user_wc.current_user.me().user_name

agent = Agent(
    name="my-agent",
    instructions=(
        "When the user asks who they are, call the whoami tool "
        "and return the raw result."
    ),
    model="databricks-claude-sonnet-4-6",
    tools=[whoami],
)

エージェントを再デプロイします。エージェントを Databricks Apps に作成してデプロイするを参照してください。

ワークスペース UI テストは最も迅速な健全性チェックであり、 OAuthトークンを必要としません。

  1. スコープの変更はすぐに有効になりますが、内部キャッシュが更新されるまでに最大5分かかることがあります。そのため、テストを行う前にその間お待ちください (アプリの再起動は不要です)。アプリのURLのブラウザのCookieを常にクリアしてください (ステップについては下記のドロップダウンを参照してください)。そうしないと、セッションがスコープ変更前に発行されたトークンを再利用します。
  2. アプリでCAN USE権限があることを確認してください。Databricks アプリのアクセス許可を構成するを参照してください。
  3. ブラウザでアプリのURLを開きます。初回アクセス時に、リクエストされたスコープの同意プロンプトを受け入れます。
  4. チャットでWho am I?を尋ね、エージェントがあなたのユーザー名を返すことを確認してください (例: you@your-company.com)。

Chrome で Cookie をクリアします

  1. DevToolsを開く： F12 、macOSの場合は Cmd+Option+I 、WindowsまたはLinuxの場合は Ctrl+Shift+I を押します。
  2. アプリケーション tab を開きます。
  3. 「**ストレージ**> **Cookie**」の下で、アプリのURLを選択します。
  4. 各Cookieを右クリックし、 削除 を選択します。

Chrome DevTools では、「アプリケーション」tab、アプリケーションURLのCookie、および右クリックの「削除」メニューが表示されます。

ツールがユーザー名の代わりにUUIDを返す場合、x-forwarded-access-tokenヘッダーがツールに到達しておらず、エージェントはアプリのDatabricks Service Principalにフォールバックしました(UUIDはアプリのService PrincipalクライアントIDです)。診断するには、以下をそれぞれ確認します:

  1. ユーザー認証はワークスペースで有効になっています。
  2. アプリにスコープが構成されています。
  3. get_user_workspace_client() @invokeまたは@streamハンドラー内で呼び出され、アプリのStartupでは呼び出されません。
  4. コードはget_user_workspace_client()を使用しており、WorkspaceClient()は使用していません。

注意すべき点がいくつかあります：

  • 本番運用前に whoami ツールを削除してください。 これは診断専用であり、エージェントを呼び出すことができるすべてのユーザーにユーザー ID を公開します。
  • **2番目のユーザーでテストします。** シングルユーザーチェックにより、トークンが転送されることが確認されます。2番目の呼び出し元は、共有fallbackの代わりに各リクエストが独自のIDを取得することを確認します。
  • **転送されたトークンをログに記録しないでください。** ユーザー認証のベストプラクティスを参照してください。
  • 特定のスコープを確認するには 、current_user.me() を、そのスコープを必要とする呼び出しに置き換えます。たとえば、warehouseに対するSELECT current_user()ステートメントは、sqlスコープをエンドツーエンドで実行します。

Databricks MCPサーバーに認証します​

DatabricksマネージドMCPサーバーは、AI SearchインデックスおよびUnity Catalog関数を、https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> および https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema> の形式のURLを介してツールとして公開します。レガシー/api/2.0/mcp/vector-search/ URLプレフィックスは、下位互換性のために引き続き機能します。利用可能なサーバーとそのURLパターンの一覧については、DatabricksマネージドMCPサーバーを参照してください。

認証するには、エージェントの Service Principal（またはユーザー認可を使用している場合はユーザー）に、それらのスキーマ内のすべてのダウンストリームリソースへのアクセス権を付与します。

例えば、エージェントが以下のMCPサーバーURLを使用する場合：

  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/customer_support
  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/billing
  • https://<your-workspace>/api/2.0/mcp/functions/prod/billing

prod.customer_support および prod.billing のすべての AI Search インデックスと、prod.billing のすべての Unity Catalog 関数にアクセス権を付与する必要があります。

各インデックスと関数を App リソース の下にリソースとして追加します。他のDatabricksリソースへの権限の付与と同じステップに従ってください。

MCPサービスへの認証​

前のセクションでは、独自のUnity Catalogデータと関数を公開するマネージドMCPサーバーについて説明しました。 MCPサービス は異なります。これらは、ユーザーが登録する外部MCPサーバーと、DatabricksがサードパーティのSaaSツール向けに提供する組み込みのsystem.ai.*サービス（system.ai.google_calendarなど）を対象としています。どちらの種類もhttps://<workspace>/ai-gateway/mcp-services/<catalog>.<schema>.<mcp-service>のUnityゲートウェイを通じて呼び出され、どちらも同じ方法で認証されます。

各MCPサービスは独自のUnity Catalogセキュリティ保護可能なオブジェクトであるため、一度に1つのサービスに対してアクセス権を付与します。

呼び出し元にサービスへのアクセス権を付与する​

サービスを呼び出すには、呼び出し元はそのサービスに対するEXECUTE USE CATALOG``USE SCHEMAに加え、その親カタログおよびスキーマに対する および が必要です。EXECUTE だけでは不十分です。Unity Catalogは親チェーンもチェックするためです（チームメイトへのアクセス権の付与を参照してください）。

組み込みのsystem.ai.*サービスの場合、アカウントユーザーはdefaultですでにこれらの権限を保持しているため、通常は権限を付与する必要はありません。

独自のカタログおよびスキーマ内のサービスについては、呼び出し元に権限を付与します。アプリIDアクセスにはアプリの Databricks Service Principal を、代理アクセスには呼び出し元のユーザーまたはグループを指定してください。カタログエクスプローラーの Permissions tab、または REST API を使用します（<catalog>.<schema>.<service> は独自のものに置き換えてください）。

Bash
databricks api patch "/api/2.1/unity-catalog/permissions/mcp_service/<catalog>.<schema>.<service>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["EXECUTE"] } ] }'
databricks api patch "/api/2.1/unity-catalog/permissions/catalog/<catalog>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["USE_CATALOG"] } ] }'
databricks api patch "/api/2.1/unity-catalog/permissions/schema/<catalog>.<schema>" \
  --json '{ "changes": [ { "principal": "data-team", "add": ["USE_SCHEMA"] } ] }'

代理アクセス用にユーザーのトークンを転送する​

ユーザー代理アクセスは各呼び出しを呼び出し元のユーザーとして実行するため、アプリはユーザーのトークンをUnity Gatewayに転送することを許可されている必要があります。ai-gateway ユーザーAPIスコープを追加してこれを有効にします：アプリリソースで user_api_scopes: [ai-gateway] を宣言し（「アプリへのスコープの追加」を参照）、「エージェントの作成とDatabricks Appsへのデプロイ」にあるユーザーごとのクライアント（get_user_workspace_client()）を使用してサービスを呼び出します。

各ユーザーが初めてサービスを呼び出す際に、承認を行う必要があります。承認が行われるまで、呼び出しは error.data.elicitations[] 内のログイン url を伴う JSON-RPC エラー -32042 を返します。ユーザーがアプリ内で承認できるようにそのLinkを表示するか、カタログエクスプローラーでサービスを開いて 「ログイン」 をクリックするようにユーザーに案内してください。

注記

バンドルを通じてこのEXECUTEのアクセス権を付与することはできません。Declarative Automation Bundlesのuc_securableリソースは、VOLUME、TABLE、FUNCTION、CONNECTIONの保護対象のみをサポートしており、MCPサービスはサポートしていません。そのため、UIまたは上記のREST APIを使用して、EXECUTEを個別に付与する必要があります。注意: databricks bundle validateは権限付与の欠落をフラグ付けしないため、エージェントは正常にデプロイできても、サービスを最初に呼び出すときに失敗する可能性があります。

独自の Databricks アプリとしてホストされているカスタム MCP サーバー（アプリ名が mcp- で始まる）は、バンドルリソースとしてまだサポートされていません。エージェントのService Principal Can Useを、MCPサーバーアプリでdatabricks apps update-permissionsを使用して手動で付与します。エージェントTemplateリポジトリのcustom-mcp-server skillを参照してください。

次のステップ​

このページの見出し