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

チュートリアル: RBACを使用して AI エージェントのアクセスをスコープ指定する

役割ベースのアクセス制御 (RBAC)を使用して、AIエージェントが特定のタスクに必要なデータとリソースにアクセスできる範囲を制限します。役割にスコープされたOAuthトークンをエージェントに提供します。そのトークンで行われたリクエストは、認証ユーザーまたはDatabricks Service Principalの広範な権限ではなく、ロールの権限を使用します。

シナリオ​

AI サポートエージェントにはチケットのサマリーとステータスが必要ですが、個人識別情報 (PII) を含む顧客の連絡先情報は必要ありません。その認証用 Databricks Service Principal は、より広範なアクセス権を持っており、両方のデータセットを読み取ることができます。

この例では、support.tickets スキーマには、顧客のPIIを含まないチケットの概要とステータスが含まれています。顧客の連絡先詳細は support.customers.contact_details に個別に保存されます。

role-support-agent を作成し、support.tickets への読み取りアクセス権を付与し、Databricks Service Principal にその権限を想定する権限を付与します。そのロールにスコープされたトークンがあれば、エージェントはサポートチケットを読み取ることはできますが、顧客の連絡先情報にはアクセスできません。

ロールは親グループからデータ権限を継承でき、カタログまたはスキーマの付与はその下にあるすべてのテーブルに適用できます。この例では、これらの付与によってロールに顧客連絡先テーブルへのアクセス権が与えられないことを確認してください。権限の継承を参照してください。共有権限を変更すると他のユーザーやロールに影響するため、他のユーザーのアクセス権を削除する代わりにテストワークスペースを使用してください。

このチュートリアルは、提供した OAuth アクセストークンを受け入れるカスタムの自己ホスト型、またはサードパーティのエージェントを対象としています。Databricks Apps にデプロイされたエージェントの場合、組み込みのアプリまたはユーザー認証を使用します。エージェントの認証を参照してください。

前提条件​

  • RBAC が有効な Unity Catalog 有効化ワークスペース。RBAC を有効にするを参照してください。
  • ロールを作成し、Assume権限を付与し、それをワークスペースに割り当てるためのアカウント管理者またはワークスペース管理者権限。「グループを管理できるユーザー」を参照してください。
  • supportカタログの所有権またはMANAGE。
  • ワークスペース管理者権限、またはこの例で使用するSQLウェアハウスに対する「管理可能」権限。
  • 既存のテーブルsupport.tickets.open_casesとsupport.customers.contact_details。必要に応じて、架空のテストデータを使用し、独自の名前に置き換えてください。
  • Databricks SQLアクセス、SQL warehouseに対する使用権限、および両方のテーブルに対するクエリー権限を持つ、ワークスペースに割り当てられたDatabricks Service Principal。マシン間（M2M）認証のための sql スコープを許可するOAuthシークレットが必要です。ステップ1: OAuthシークレットを作成するを参照してください。
  • curl トークンをリクエストしてテストできる信頼できる環境。
  • system.access.auditにアクセスできる監査リーダーが、ロール下のエージェントの活動を検証します。監査属性の検証を参照してください。

ステップ1：ロールを作成する​

このチュートリアルでは、ロールとして機能する空のアカウントグループを作成します。

  1. アカウント管理者として、アカウントコンソールにログインします。
  2. サイドバーで、[ ユーザー管理 ] をクリックします。
  3. [ グループ ] タブで、[ グループの追加 ] をクリックします。
  4. role-support-agentを入力します。メンバーを追加しないでください。
  5. 確認 をクリックします。
  6. Databricks SQLアクセス を使用して、グループをワークスペースに割り当てます。ワークスペースにグループを割り当てるを参照してください。

Databricks SQLアクセス権は、ダッシュボード、クエリー、SQL WarehouseなどのDatabricks SQL機能へのアクセス権を付与します。この例ではSQLクエリーを使用します。エージェントがノートブック、ジョブ、モデル、パイプラインなどのコアワークスペース機能も必要とする場合は、ワークスペースアクセス権を付与します。「アクセス権限」を参照してください。データ権限とwarehouse権限はステップ2で設定します。

この例では、Databricks service principalをメンバーとして追加する代わりに、Assumeアクセス許可を個別に付与します。メンバーシップにより、グループのアクセス許可がDatabricks Service Principal自体のIDにも追加されます。

ステップ 2: ロールにサポートチケットへのアクセス権を付与する​

カタログ所有者またはsupportでMANAGEを持つユーザーとして、次をラン：

SQL
GRANT USE CATALOG ON CATALOG support TO `role-support-agent`;
GRANT USE SCHEMA, SELECT ON SCHEMA support.tickets TO `role-support-agent`;

ワークスペース管理者またはwarehouseに対して「管理可能」を持つユーザーは、そのロールにwarehouseへのアクセス権を付与します：

  1. ワークスペースのサイドバーで、[ SQL ウェアハウス ] をクリックします。
  2. Warehouseの横にある ケバブメニューアイコン。 ケバブメニューをクリックし、 [権限] をクリックします。
  3. role-support-agentを 使用可能 で追加します。

スキーマレベルの SELECT 付与は、support.tickets 内の現在および将来のすべてのテーブルとビューに適用されます。support.customers や他のスキーマへのアクセスは許可されません。ロールを単一のテーブルに制限するには、代わりにそのテーブルで SELECT を付与します。Unity Catalog での権限の管理を参照してください。

ステップ 3：ロールを引き受ける権限を付与する​

いずれかの方法を使用して、Databricks Service PrincipalにAssume権限を付与します。

  1. アカウント管理者としてアカウントコンソールを開き、[ ユーザー管理 ] をクリックします。
  2. グループ tabで、role-support-agent をクリックします。
  3. アクセス許可 tabをクリックし、 アクセス許可を付与 をクリックします。
  4. Databricks Service Principalを検索して選択し、 Assume を選択して Save をクリックします。

ステップ4: ロールスコープのトークンを要求する​

信頼できるトークン要求環境で、これらの環境変数を設定します。

  • DATABRICKS_HOST：https://を含み、末尾にスラッシュがないワークスペースURL。
  • CLIENT_ID およびCLIENT_SECRET：Databricks Service PrincipalのアプリケーションIDとOAuthシークレット。
  • ROLE_GROUP_ID：role-support-agentの数値ID。アカウント管理者は、アカウントコンソールのグループのURLの末尾でそれを見つけることができます。アカウント管理者、ワークスペース管理者、およびグループマネージャーは、アカウントグループAPIを使用してグループのidを取得することもできます。
  • DATABRICKS_SQL_WAREHOUSE_ID：ステップ2で許可された warehouse の ID です。warehouse の HTTP パス 内で /sql/1.0/warehouses/ の後に続きます。Databricks コンピュート リソースの接続の詳細を取得するを参照してください。

assume_group パラメーターと sql OAuth スコープを使用して、ワークスペースレベルのトークンをリクエストします。スコープにより、トークンは SQL APIs に制限されます。ロールのデータ権限によって、クエリー可能なテーブルが決まります。スコープ付き OAuth シークレットを参照してください。

トークンを要求するには、以下をラン：

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/oidc/v1/token" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=sql' \
  --data-urlencode "assume_group=$ROLE_GROUP_ID"

DATABRICKS_TOKENにレスポンスのaccess_tokenの値を設定します。expires_inの値を使用して、交換の要求時期を決定します。アカウントレベルのトークン要求は assume_group をサポートしていません。ロールを引き受けるを参照してください。

ステップ5：トークンのアクセス権を確認する​

トークンをエージェントに提供する前に、これらのチェックを信頼された環境でランしてください。

まず、Databricks Service Principal自身のIDのトークンを使用してベースラインを取得します。ステップ4のリクエストをassume_groupパラメーターなしで繰り返し、DATABRICKS_TOKENをそのトークンに一時的に設定します。このステップの両方のクエリーをランし、成功することを確認します。次に、DATABRICKS_TOKENをロールスコープトークンに戻し、チェックを繰り返します。

サポートチケットの読み取り​

ロールスコープのトークンを使用してこのリクエストをランします：

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT * FROM support.tickets.open_cases LIMIT 10\",
    \"wait_timeout\": \"50s\"
  }"

ロールがsupport.ticketsを読み取ることができるため、クエリーは成功します。応答のstatus.stateがSUCCEEDEDであることを確認してください。PENDINGまたはRUNNINGの場合、返されたstatement_idを使用して、同じトークンで結果を取得します：

Bash
curl --request GET \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements/<statement-id>" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN"

文のステータスと結果の処理については、Statement Execution API: ラン SQL on warehouseを参照してください。

顧客のPIIへのアクセスが拒否されていることを確認します​

同じロールスコープトークンとwarehouseを使用して、以下を実行します。

Bash
curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT 1 FROM support.customers.contact_details LIMIT 1\",
    \"wait_timeout\": \"50s\"
  }"

ステートメントがまだ実行中の場合は、前のセクションで説明したように結果を取得します。クエリーはstatus.errorのアクセス権限エラーで失敗しますが、Databricks Service Principal自身のトークンでは成功します。HTTP成功レスポンスだけでは、クエリーが成功したとはいえません。テーブルがない、トークンの有効期限が切れている、またはWarehouseのエラーが発生している場合、そのロールのデータ権限が正しく構成されているとは判断できません。

監査の帰属を確認する​

監査属性の検証で説明されているアクセス権を持つ監査リーダーを使用します。system.access.auditでテストクエリーイベントを検査します。identity_metadata.run_asは認可ロールを特定し、run_as_display_nameにはrole-support-agentが含まれ、run_byはリクエストを開始したDatabricks Service Principalを特定します。監査データは1日を通して更新されるため、最近のイベントはすぐには表示されない場合があります。ID メタデータのリファレンスを参照してください。

ステップ6: エージェントを設定する​

エージェントのDatabricksクライアントにワークスペースURLと検証済みロールスコープトークンを設定します。そのトークンのみをエージェントに提供し、Databricks Service PrincipalのOAuthシークレットやスコープ指定されていないトークンは提供しないでください。ロールスコープトークンは、そのトークンで行われるリクエストを制限します。他のセッションでのDatabricks Service Principalの権限は削除されません。

Databricks SDK for Pythonを使用するエージェントの場合は、エージェントの環境でDATABRICKS_HOSTとDATABRICKS_TOKENを設定し、クライアントを初期化します。

Python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

SDKは、統合認証を使用して環境からトークンを読み取ります。アクセストークンを提供しても、新しいトークンを要求するために必要な資格情報がSDKに与えられるわけではありません。長時間実行されるエージェントの場合は、トークンの有効期限が切れる前に、信頼できるコンポーネントが役割スコープのトークンを要求して提供できるように準備してください。

オプション：開発者のIDを使用する​

ユーザー対マシン (U2M) 認証を使用したローカルテストの場合、ステップ3と同様に、参加する開発者にrole-support-agentの「Assume」権限を付与します。開発者は「Databricks CLIのインストールまたはアップデート」の説明に従って Databricks CLI をインストールし、自身のサインインと個別のプロファイルを使用して認証します。

Bash
databricks auth login --host <workspace-url> --profile support-agent

開発者はブラウザで 「Authorize as..（として認可）」 の下のrole-support-agentを選択して 「Continue（続行）」 をクリックし、そのプロファイルのトークンを取得します。

Bash
databricks auth token --profile support-agent

開発者は、返されたaccess_tokenをステップ5のロールスコープクエリーチェックのDATABRICKS_TOKENとして使用します。これらのリクエストの監査イベントでは、開発者はrun_byとして識別されます。Databricks CLIによって返されるトークンは期限切れになります。開発者は必要に応じて新しいトークンを取得します。API (OAuthアクセストークン)を参照してください。

クリーンアップ​

一時的なテストの場合、完了したらエージェントのトークン構成を削除し、テスト用に作成された「Assume（引き受け）」権限の付与を取り消してください。ロールを削除する前に、それが資産を所有しているか、または他のワークロードによって使用されていないかを確認してください。

次のステップ​

このページの見出し