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

AI エージェントの認証

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

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

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

手法

説明

使用する場合

アプリ認可

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

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

ユーザー認可

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

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

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

ワークスペースUIまたは宣言型オートメーションバンドルで認証を構成します。​

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

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

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

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

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

アプリの認可​

デフォルトでは、Databricks Appsはアプリ認証を使用して認証します。Databricksはアプリを作成する際にサービスプリンシパルを自動的に作成し、それがアプリのIDとして機能します。

アプリと対話するすべてのユーザーは、サービスプリンシパル用に定義された同じ権限を共有します。このモデルは、すべてのユーザーが同じデータを見たい場合、またはアプリがユーザー固有のアクセスコントロールに縛られない共有操作を実行する場合にうまく機能します。

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

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

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

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

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

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

エージェントが Genie Spaces、AI Search インデックス、SQLウェアハウスなどの他の Databricks リソースを使用する場合は、各リソースでサービスプリンシパル権限を付与します。

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

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

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

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

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

次の表に、上記の例で使用されている最小限の権限と、各リソースタイプに対応するDeclarative Automation Bundlesの値を一覧表示します。

リソースタイプ

ワークスペース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

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

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

ユーザー認証​

備考

プレビュー

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

ユーザー認可により、エージェントは要求を行うユーザーの ID で動作できます。以下を提供します:

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

エージェントが、アプリケーションのサービスプリンシパルの代わりにリクエスト元のユーザーの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スペース
  • ファイルとディレクトリ
  • モデルサービングエンドポイント
  • AI Search インデックス
  • Unity Catalog接続
  • Unity Catalogテーブル

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

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

  1. Databricks UIで、アプリの**認可**設定に移動します。
  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. アプリの起動時ではなく、クエリ時にワークスペースクライアントを初期化します。

重要

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

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() はデフォルトの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],
)

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

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

  1. スコープの変更はすぐに有効になりますが、内部キャッシュが更新されるまでに最大5分かかる場合があります。テストする前にその間お待ちください (アプリの再起動は不要です)。アプリのURLのブラウザクッキーを常にクリアしてください (ステップについては以下のドロップダウンを参照してください)。そうしないと、スコープ変更前に発行されたトークンがセッションで再利用されます。
  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. Application タブを開きます。
  3. Storage > Cookies で、アプリの URL を選択します。
  4. 各 Cookie を右クリックし、 削除 を選択します。

Application タブ、アプリ URL の cookie、および右クリックの［Delete］メニューを示す Chrome DevTools。

ツールがユーザー名の代わりにUUIDを返す場合、x-forwarded-access-tokenヘッダーがツールに到達しておらず、エージェントがアプリのDatabricksサービスプリンシパルにフォールバックしました（UUIDはアプリのサービスプリンシパルのクライアントIDです）。診断するには、次のそれぞれを確認してください。

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

注意すべき点:

  • whoami[**本番運用前に ツールを削除してください。**] これは診断専用であり、エージェントを呼び出せるすべてのユーザーにユーザーIDを公開します。
  • 2番目のユーザーでテストします。 シングルユーザーチェックはトークンが転送されることを確認し、2番目の呼び出し元は、共有のフォールバックではなく、各リクエストが独自のIDを取得することを確認します。
  • 転送されたトークンはログに記録しないでください。 ユーザー承認のベストプラクティスを参照してください。
  • 特定のスコープを検証するには 、current_user.me()をそのスコープを必要とする呼び出しで置き換えてください。例えば、ウェアハウスに対する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 サーバーを参照してください。

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

たとえば、エージェントが次の 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 関数にアクセス権を付与する必要があります。

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

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

次のステップ​

このページの見出し