AI エージェントの認証

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

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

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

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

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

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

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

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

どちらのパスでも、同じランタイム構成が生成されます。 このページの残りの部分では、両方のフォームの各指示が表示されるので、1 つを選択してプロジェクト内で一貫性を保つことができます。

いずれかのパスを使用してアプリにリソースを追加するには、リソースとアプリの両方に対する Can Manage アクセス許可が必要です。

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

アプリの承認

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

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

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

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

トレースと評価結果をログに記録するには、エージェントが MLflow 実験にアクセスする必要があります。 実験に対するアクセス許可 Can Edit サービス プリンシパルに付与します。

ワークスペース UI

  1. アプリのホーム ページで [ 編集] をクリックします。
  2. [構成] ステップに移動します。
  3. [ アプリ リソース ] セクションで、 Can Edit アクセス許可を持つ MLflow 実験リソースを追加します。

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

宣言型オートメーション バンドル

  1. アプリのdatabricks.ymlリスト内でresourcesを宣言して実験を行います。 リソースに割り当てる name は、後で環境変数を接続するときに参照されます。

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

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

    databricks bundle deploy
databricks bundle run my_agent

すべてのフィールドについては 、app.resources.experiment を参照してください。

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

エージェントで Genie スペース、Vector Search インデックス、SQL ウェアハウスなど、他の Databricks リソースを使用している場合は、それぞれにサービス プリンシパルのアクセス許可を付与します。

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

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

ワークスペース UI

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

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

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

宣言型オートメーション バンドル

  1. エージェントが使用するすべてのリソースを、resourcesのアプリのdatabricks.yml一覧で宣言します。 次の例は、MLflow 実験、サービス エンドポイント、Genie 空間、SQL ウェアハウス、ベクター検索インデックス、Unity カタログ関数、Lakebase インスタンスを使用するエージェントを示しています。 各リソース name は config.env から value_from 経由で参照されるため、エージェントは実行時に解決された識別子を受け取ります。

    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

    Important

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

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

    databricks bundle validate
databricks bundle deploy
databricks bundle run my_agent

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

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

次の表に、上記の例で使用されている最小限のアクセス許可と、リソースの種類ごとに同等の宣言型オートメーション バンドルの値を示します。

リソースの種類 ワークスペース UI のアクセス許可 宣言型オートメーション バンドルのリソースとアクセス許可
SQL ウェアハウス Can Use sql_warehouse と CAN_USE
モデル サービング エンドポイント Can Query serving_endpoint と CAN_QUERY
Unity カタログ関数 Can Execute uc_securable securable_type: FUNCTIONとEXECUTEを含めて
ジーニー空間 Can Run genie_space と CAN_RUN
ベクトル検索インデックス Can Select uc_securable securable_type: TABLEとSELECTを含めて
Unity カタログ テーブル SELECT uc_securable securable_type: TABLEとSELECTを含めて
Unity カタログ接続 Use Connection uc_securable securable_type: CONNECTIONとUSE_CONNECTIONを含めて
Unity カタログ ボリューム 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

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

ユーザーの承認

Important

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

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

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

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

ユーザー承認のしくみ

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

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

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

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

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

ユーザー承認を実装する

ユーザー承認を実装するには、承認スコープをアプリに追加する必要があります。 スコープによって、アプリがユーザーに代わって実行できる操作が制限されます。 使用可能なスコープとスコープセマンティクスの一覧については、「 スコープベースのセキュリティと特権のエスカレーション」を参照してください。

ワークスペース UI

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

宣言型オートメーション バンドル

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

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

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

    databricks bundle deploy
databricks bundle run my_agent

    Note

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

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

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

    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 ヘッダーをキャプチャし、それらのユーザー資格情報を使用してワークスペース クライアントを構築し、ユーザー、アプリ、およびエージェント サーバー間の認証を処理します。

  2. アプリの起動時ではなく、クエリ時にワークスペース クライアントを初期化します。

    Important

    get_user_workspace_client()ハンドラーとinvokeハンドラー内でstreamを呼び出し、__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 サーバーは、 https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> および https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>フォームの URL を使用して、Vector Search インデックスと Unity カタログ関数をツールとして公開します。 使用可能なサーバーとその 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 カタログ関数へのアクセス権を付与する必要があります。

ワークスペース UI

各インデックスと関数をリソースとして [アプリ リソース] に追加します。 他の Databricks リソースにアクセス許可を付与するのと同じ手順に従います。

宣言型オートメーション バンドル

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

    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. バンドルを再デプロイします。

    databricks bundle deploy
databricks bundle run my_agent

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

次のステップ

  • Last updated on