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

AI エージェントの認証

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

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

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

手法

説明

いつ使うか

アプリ認可

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

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

ユーザー認可

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

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

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

アプリの認可​

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

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

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

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

エージェントは、トレースと評価結果をログに記録するためにMLflowエクスペリメントにアクセスする必要があります。

MLflowエクスペリメントに対するサービスプリンシパルCan Edit権限を付与します。

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

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

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

エージェントがGenie spaces 、一斉検索インデックス、 SQLウェアハウスなどの他のDatabricksリソースを使用している場合は、 Databricks Apps UI を通じてサービスプリンシパルのアクセス許可を付与します。 サポートされているリソースと構成手順の完全な一覧については、 「Databricks アプリにリソースを追加する」を参照してください。

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

次の表は、エージェントが一般的な Databricks リソースにアクセスするために必要な最小限の権限を示しています。

リソースタイプ

権限

SQLウェアハウス

Can Use

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

Can Query

Unity Catalog 関数

CAN Execute

Genieスペース

Can Run

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

Can Select

Unity Catalog テーブル

SELECT

Unity Catalog接続

Use Connection

Unity Catalogボリューム

Can Read または Can Read and Write

Lakebase

Can Connect and Create

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

リソースを追加するユーザーは、リソースとアプリの両方に対するCan Manage権限を持っている必要があります。サポートされているリソースの完全なリストと利用可能なすべての権限については、 「サポートされているリソースのタイプ」を参照してください。

資格情報管理や最小権限の原則など、アプリの承認を安全に管理するためのベスト プラクティスについては、 「アプリの承認」を参照してください。

ユーザー認証​

備考

プレビュー

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

ユーザー認証により、エージェントはリクエストを行うユーザーの 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 UI で、 Databricks Apps承認設定に移動します。
  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 サーバーに認証するには、エージェントに必要なすべてのリソースをdatabricks.yamlファイルで指定します。アプリのサービスプリンシパル (ユーザー認証を使用している場合はユーザー) にすべてのダウンストリーム リソースへのアクセスを許可します。

たとえば、エージェントが以下にリストされている MCP サーバー URL を使用する場合、 prod.customer_supportおよびprod.billingスキーマ内のすべてのキーワード検索インデックスと、 prod.billing内のすべてのUnity Catalog関数へのアクセスを許可する必要があります。

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

Databricks Asset Bundlesで認証を構成する​

Databricks Apps UI の代わりにDatabricksアセット バンドルを使用して、すべての認証設定をプログラムで構成できます。 このページでは、必要なリソースと権限を説明するために UI ベースの構成を示していますが、同じ構成をバンドル YAML ファイルで定義することもできます。完全なバンドル構成リファレンスについては、 「バンドル内のアプリ」を参照してください。

次のステップ​