AI エージェントの認証

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

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

Databricks Apps には、エージェント用の 2 つの認証方法が用意されています。各メソッドは、さまざまなユースケースに対応します。

メソッド	Description	いつ使用するか
アプリの承認	エージェントは、一貫性のあるアクセス許可を持つ、自動的に作成されたサービスプリンシパルを使用して認証します。以前はサービスプリンシパル認証と呼ばれています。	最も一般的なユースケース。すべてのユーザーがリソースに同じアクセス権を持つ必要がある場合に使用します。
ユーザーの承認	エージェントは、要求を行うユーザーの ID を使用して認証します。以前は「オンビハーフオブ (OBO) 認証」と呼ばれていました。	Unity Catalog でユーザー固有のアクセス許可、監査証跡、またはきめ細かなアクセス制御が必要な場合に使用します。

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

アプリの承認

既定では、Databricks Apps はアプリの承認を使用して認証します。 Azure Databricks では、アプリの作成時にサービスプリンシパルが自動的に作成され、アプリの ID として機能します。

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

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

MLflow 実験にアクセス許可を付与する

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

MLflow 実験に対するアクセス許可 Can Edit サービスプリンシパルに付与します。

アプリのホームページで [ 編集] をクリックします。
[構成] ステップに移動します。
[ アプリリソース ] セクションで、MLflow 実験リソースを追加します。

Databricks アプリへの MLflow 実験リソースの追加を参照してください。

他の Databricks リソースにアクセス許可を付与する

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

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

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

リソースの種類	権限
SQL ウェアハウス	`Can Use`
モデルサービングエンドポイント	`Can Query`
Unity カタログ関数	`CAN Execute`
ジーニー空間	`Can Run`
ベクトル検索インデックス	`Can Select`
Unity カタログテーブル	`SELECT`
Unity カタログ接続	`Use Connection`
Unity カタログボリューム	`Can Read` または `Can Read and Write`
Lakebase	`Can Connect and Create`

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

リソースを追加するユーザーには、リソースとアプリの両方に対する Can Manage アクセス許可が必要です。サポートされているリソースと使用可能なすべてのアクセス許可の完全な一覧については、サポートされているリソースの種類を参照してください。

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

ユーザーの承認

Important

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

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

機密データへのユーザーごとのアクセス
Unity カタログによって適用されるきめ細かいデータコントロール
ユーザー固有の監査証跡
行レベルフィルターと列マスクの自動適用

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

ユーザー承認のしくみ

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

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

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

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

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

ユーザー承認を実装する

ユーザー承認を実装するには、承認スコープをアプリに追加する必要があります。スコープによって、アプリがユーザーに代わって実行できる操作が制限されます。

Databricks UI で、Databricks Apps の承認設定に移動します。
[ +スコープの追加] をクリックし、ユーザーの代わりにリソースにアクセスするスコープを選択します。
変更を保存します。

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

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

databricks/app-templates から提供されたテンプレートのいずれかを使用する場合は、提供されたユーティリティをインポートします。
```
from databricks_app.utils import get_user_workspace_client
```
それ以外の場合は、エージェントサーバーユーティリティからインポートします。
```
from agent_server.utils import get_user_workspace_client
```
get_user_workspace_client()関数は、エージェントサーバーを使用してx-forwarded-access-token ヘッダーをキャプチャし、それらのユーザー資格情報を使用してワークスペースクライアントを構築し、ユーザー、アプリ、およびエージェントサーバー間の認証を処理します。
アプリの起動時ではなく、クエリ時にワークスペースクライアントを初期化します。

Important

invokeハンドラーとstreamハンドラー内でget_user_workspace_client()を呼び出し、__init__やアプリの起動時では呼び出さないようにします。ユーザー資格情報は、ユーザーが要求を行った場合にのみクエリ時に使用できます。ユーザーコンテキストがまだ存在しないため、アプリの起動時に初期化に失敗します。
```
# 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 カタログ関数へのアクセス権を付与する必要があります。

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 アセットバンドルを使用して認証を構成する

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

次のステップ

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-02-14