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

AI エージェントの認証

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

このページではDatabricks Appsにデプロイされたエージェントの認証方法について説明します。 モデルサービング エンドポイントにデプロイされたエージェントについては、 AIエージェントの認証 (モデルサービング)」を参照してください。

Databricks Appsエージェントに対して 2 つの認証方法を提供します。 それぞれの方法は、異なるユースケースに役立ちます。

手法

説明

いつ使うか

アプリ認可

エージェントは、一貫した権限を持つ自動的に作成されたサービスプリンシパルを使用して認証します。 以前はサービスプリンシパル認証と呼ばれていました。

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

ユーザー認可

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

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

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

ワークスペース UI または Declarative Automation Bundle を使用して認証を構成する​

認証設定は、以下の2つの方法で構成できます。

  • ワークスペース UI : Configure ステップからアプリを編集し、リソースとスコープを管理します。 ワークスペース内で単一のアプリを反復的に開発する場合に推奨されます。
  • 宣言型自動化バンドル : databricks.ymlファイルでリソース、スコープ、環境変数を宣言し、 databricks bundle deployを使用してデプロイします。Gitベースのバージョン管理、CI/CD、または複数のワークスペース間で同じエージェントを配布したい場合に推奨されます。すべてのエージェントテンプレートにはdatabricks.ymlが付属しています。

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

どちらの方法でもアプリにリソースを追加するには、リソースとアプリの両方に対してCan Manage権限が必要です。

バンドルの完全なリファレンスについては、 app リソースとapp. リソースを参照してください。 バンドルのエンドツーエンドの手順については、 「宣言型自動化バンドルを使用した Databricks アプリの管理」を参照してください。

アプリの認可​

もちろん、 Databricks Appsアプリの承認を使用して認証します。 Databricks 、アプリの作成時にサービス プリンシパルを自動的に作成し、それがアプリの ID として機能します。

アプリを操作するすべてのユーザーは、サービスプリンシパルに定義されているのと同じ権限を共有します。 このモデルは、すべてのユーザーに同じデータを表示させたい場合や、アプリがユーザー固有のアクセス制御に関連付けられていない共有操作を実行する場合に適しています。

アプリの承認の詳細については、 「アプリの承認」を参照してください。

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

エージェントは、トレースと評価結果をログに記録するために、 MLflow拡張機能へのアクセスが必要です。 エクスペリメントに対するサービスプリンシパルCan Edit権限を付与します。

  1. アプリのホームページで 「編集」を クリックします。
  2. 「設定」 ステップに進んでください。
  3. [アプリ リソース] セクションで、 Can Edit権限を持つMLflowエクスペリメント リソースを追加します。

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

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

エージェントがGenie Spaces、一斉検索インデックス、 SQLウェアハウスなどの他のDatabricksリソースを使用している場合は、それぞれにサービスプリンシパルのアクセス許可を付与します。

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

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

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

  1. アプリのホームページで 「編集」を クリックします。
  2. 「設定」 ステップに進んでください。
  3. [アプリ リソース] で、エージェントが使用するリソースごとに [+ リソースの追加] をクリックし、権限を設定します。

サポートされているリソースの完全なリストとスクリーンショットについては、 「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スペース

Can Run

genie_space と CAN_RUN

ベクトル検索インデックス

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

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

ユーザー認証​

備考

プレビュー

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

ユーザー認証により、エージェントはリクエストを行うユーザーの ID を使用して動作できるようになります。これにより、次のことが実現されます。

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

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

ユーザー認証の仕組み​

エージェントのユーザー認証を構成する場合:

  1. アプリにAPIスコープを追加する : ユーザーに代わってアプリがアクセスできるDatabricks APIs定義します。 「アプリにスコープを追加する」を参照してください。
  2. ユーザー資格情報はダウンスコープされます : Databricks はユーザーの資格情報を取得し、定義した API スコープのみに制限します。
  3. 場合転送 : ダウンスコープされたウィザードは、 x-forwarded-access-token HTTP ヘッダーを通じてアプリで利用できるようになります。
  4. MLflow AgentServer はトークンを保存します 。エージェント サーバーは、エージェント コードで簡単にアクセスできるように、要求ごとにこのトークンを自動的に保存します。

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

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

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

ユーザー認証を実装する​

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

  1. Databricksのユーザーインターフェースで、アプリの 認証 設定に移動します。
  2. 「ユーザー認証」 の下にある 「+ スコープを追加」 をクリックし、アプリがユーザーに代わってリソースにアクセスするために必要なスコープを選択します。
  3. 変更を保存してアプリを再起動してください。

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

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

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

    Python
    from databricks_app.utils import get_user_workspace_client

    それ以外の場合は、エージェント サーバー ユーティリティからインポートします。

    Python
    from agent_server.utils import get_user_workspace_client

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

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

重要

__init__内やアプリの起動時ではなく、 invokeおよびstreamハンドラー内でget_user_workspace_client()呼び出します。ユーザー資格情報は、ユーザーがリクエストを行ったクエリ時にのみ利用できます。ユーザー コンテキストがまだ存在しないため、アプリの起動中に初期化することはできません。

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)

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

Databricks MCP サーバーへの認証​

Databricksで管理される MCP サーバーは、 https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema>およびhttps://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>形式の URL を介して、一斉検索インデックスとUnity Catalog機能をツールとして公開します。 利用可能なサーバーとそのURLパターンの一覧については、 「Databricks管理のMCPサーバーを使用する」を参照してください。

認証を行うには、エージェントのサービスプリンシパル（またはユーザー認証を使用している場合はユーザー）に、これらのスキーマ内のすべての下流リソースへのアクセス権を付与します。

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

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

prod.customer_supportとprod.billingのすべての暇検索インデックス、およびprod.billingのすべてのUnity Catalog関数へのアクセスを許可する必要があります。

各インデックスと関数をリソースとして [アプリ リソース] に追加します。 他のDatabricksへのアクセス許可を付与するのと同じステップに従います。

独自の Databricks アプリとしてホストされているカスタム MCP サーバー (アプリ名にmcp-がプレフィックスとして付加される) は、バンドル リソースとしてはまだサポートされていません。MCPサーバーアプリ上で、 databricks apps update-permissionsを使用してエージェントのサービスプリンシパルCan Use手動で付与します。エージェントテンプレートリポジトリにあるcustom-mcp-serverスキルを参照してください。

次のステップ​

このページの見出し