AIエージェントの認証

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

このページでは、Databricks Appsにデプロイされたエージェントの認証方法について説明します。Model Serving Endpointにデプロイされたエージェントについては、AIエージェントの認証 (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 権限を付与します。

Workspace UI

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

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

Declarative Automation Bundles

1. databricks.ymlにあるアプリのresourcesリストでエクスペリメントを宣言します。リソースに割り当てるnameは、環境変数を設定する際に後で参照されます。

   YAML

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'

2. バンドルを再デプロイします。

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

すべてのフィールドについては、app.リソース.エクスペリメント を参照してください。

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

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

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

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

Workspace UI

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

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

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

Declarative Automation Bundles

1. databricks.ymlにあるアプリのresourcesリストで、エージェントが使用するすべてのリソースを宣言します。以下の例は、MLflowエクスペリメント、サービングEndpoint、Genie Agent、SQL Warehouse、AI検索インデックス、Unity Catalog関数、およびLakebaseインスタンスを使用するエージェントを示しています。各リソースnameはconfig.envからvalue_fromを通じて参照されるため、エージェントはランタイム時に解決された識別子を受け取ります。

   YAML

   bundle:
     name: my_agent
   
   resources:
     apps:
       my_agent:
         name: 'my-agent'
         description: 'Custom agent deployed on Databricks Apps'
         source_code_path: ./
         config:
           command: ['uv', 'run', 'start-app']
           env:
             - name: MLFLOW_EXPERIMENT_ID
               value_from: 'experiment'
             - name: LAKEBASE_INSTANCE_NAME
               value_from: 'database'
   
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'
   
           - name: 'llm'
             serving_endpoint:
               name: 'databricks-claude-sonnet-4-5'
               permission: 'CAN_QUERY'
   
           - name: 'sales-genie'
             genie_space:
               space_id: '<genie-space-id>'
               permission: 'CAN_RUN'
   
           - name: 'warehouse'
             sql_warehouse:
               id: '<warehouse-id>'
               permission: 'CAN_USE'
   
           - name: 'docs-index'
             uc_securable:
               securable_full_name: 'main.docs.chunks_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'lookup-function'
             uc_securable:
               securable_full_name: 'main.tools.order_lookup'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'
   
           - name: 'database'
             database:
               instance_name: '<lakebase-instance-name>'
               database_name: 'databricks_postgres'
               permission: 'CAN_CONNECT_AND_CREATE'
   
   targets:
     dev:
       mode: development
       default: true

重要

config.envのすべてのvalue_from値は、resourcesリストのnameフィールドと一致する必要があります。不一致により、環境変数がデプロイされたアプリでNoneに解決されます。

2. バンドルをデプロイして起動します。

   Bash

   databricks bundle validate
   databricks bundle deploy
   databricks bundle run my_agent

   bundle deploy ソースをuploadし、リソースを構成します。bundle run は、最新のソースでアプリを起動または再起動します。bundle runへの引数は、デプロイされたアプリのnameフィールドではなく、resources.appsの下のYAMLキーです（ここではmy_agent）。

各リソースサブタイプの完全なスキーマについては、app.リソースを参照してください。

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

リソースタイプ	ワークスペース 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テーブル

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

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

Workspace UI

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

Declarative Automation Bundles

1. databricks.ymlのアプリリソースのuser_api_scopesでスコープを宣言します。

   YAML

   resources:
     apps:
       my_agent:
         name: 'my-agent'
         source_code_path: ./
         user_api_scopes:
           - sql
           - genie
           - model-serving
         resources:
           - name: 'experiment'
             experiment:
               experiment_id: '<experiment-id>'
               permission: 'CAN_EDIT'

2. バンドルを再デプロイし、アプリを再起動します:

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

注記

ワークスペースでユーザー承認を初めて有効にした後、スコープを使用する前に既存のアプリを再起動する必要があります。アプリにスコープを追加するを参照してください。

エージェントコードでユーザー認証を設定するには、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],
)

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

Workspace UI

ワークスペース 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を右クリックし、 削除 を選択します。

Python

CLIプロファイルまたはDatabricksサービス プリンシパル資格情報を使用して、エージェントを呼び出します。 クエリ オプションについては「 Databricksにデプロイされたエージェントをクエリする」を参照し、 OAuthトークンを生成する方法については「トークン認証を使用してAPI Databricksアプリに接続する」を参照してください。

1. スコープの変更はすぐに有効になりますが、内部キャッシュが更新されるまでに最大5分かかる場合があるため、テストの前に待機してください（アプリの再起動は不要です）。

2. 自分自身としてエージェントを呼び出します。

   Python

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   app_name = "<your-app-name>"
   prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]
   
   w = WorkspaceClient(profile="<your-profile>")
   client = DatabricksOpenAI(workspace_client=w)
   response = client.responses.create(model=f"apps/{app_name}", input=prompt)
   print(response.output_text)

   出力はユーザー名になります — たとえば、you@your-company.comです。

ツールがユーザー名の代わりに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 関数にアクセス権を付与する必要があります。

Workspace UI

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

Declarative Automation Bundles

1. アプリのresourcesリストの下に、インデックスごと、関数ごとにuc_securableエントリを1つ追加します。

   YAML

   resources:
     apps:
       my_agent:
         resources:
           - name: 'support-index'
             uc_securable:
               securable_full_name: 'prod.customer_support.tickets_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'billing-index'
             uc_securable:
               securable_full_name: 'prod.billing.invoices_index'
               securable_type: 'TABLE'
               permission: 'SELECT'
   
           - name: 'refund-function'
             uc_securable:
               securable_full_name: 'prod.billing.process_refund'
               securable_type: 'FUNCTION'
               permission: 'EXECUTE'

2. バンドルを再デプロイします。

   Bash

   databricks bundle deploy
   databricks bundle run my_agent

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

次のステップ

• AIエージェントを作成し、Databricks Apps にデプロイします
• 宣言型オートメーションバンドルを使用したDatabricksアプリの管理
• Databricks アプリで認可の設定をする
• Databricks アプリにリソースを追加する
• アプリのリソースリファレンス