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

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)

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

ユーザー認証を確認する​

スコープを追加して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 のブラウザー Cookie を常にクリアしてください (ステップについては、以下のドロップダウンを参照してください)。そうしないと、セッションはスコープ変更前に発行された VPN を再利用します。
  2. アプリに対する権限がCAN USEであることを確認してください。Databricksアプリの権限設定を参照してください。
  3. アプリのURLをブラウザで開いてください。初回訪問時には、要求された範囲に関する同意プロンプトに同意してください。
  4. チャットでWho am I?に質問し、エージェントがあなたのユーザー名（例： you@your-company.com ）を返すことを確認してください。

Chromeでクッキーを削除する

  1. 開発者ツールを開くには、 F12 キー を押すか、macOS の場合は Cmd+Option+I 、Windows または Linux の場合は Ctrl+Shift+I を押します 。
  2. アプリケーション タブを開きます。
  3. 「ストレージ」 ＞ 「Cookie」 で、アプリのURLを選択してください。
  4. 各クッキーを右クリックして 「削除」 を選択してください。

Chrome DevToolsの「アプリケーション」タブ、アプリのURLに対応するCookie、および右クリックメニュー「削除」が表示されている。

ツールがユーザー名ではなく UUID を返す場合、 x-forwarded-access-tokenヘッダーはツールに到達しておらず、エージェントはアプリのDatabricksプリンシパルにフォールバックします (UUID はアプリのサービスプリンシパル クライアント ID です)。 診断するには、以下の各項目を確認してください。

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

注意すべき点がいくつかあります。

  • 本番運用の前にwhoamiツールを削除してください。 これは診断専用であり、エージェントを起動できる人なら誰でもユーザーの身元を知ることができます。
  • 別のユーザーでテストしてください。 単一ユーザーによるチェックでトークンが正しく転送されたことを確認し、2番目の呼び出し元で各リクエストが共有フォールバックではなく独自のIDを取得することを確認します。
  • 転送されたトークンは絶対にログに記録しないでください。 ユーザー認証に関するベストプラクティスを参照してください。
  • 特定のスコープを検証するには 、 current_user.me()そのスコープを必要とする呼び出しに置き換えます。たとえば、ウェアハウスに対するSELECT current_user()ステートメントは、 sqlスコープをエンドツーエンドで実行します。

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スキルを参照してください。

次のステップ​

このページの見出し