Databricks アプリで承認を構成する

Databricks Apps 承認モデルは OAuth 2.0 に基づいており、アプリに割り当てられたアクセス許可と、それにアクセスするユーザーのアクセス許可を組み合わせます。 アプリはワークスペース内のデータやサービスにアクセスするため、認証と認可を用いてデータアクセス制御を強制し、ユーザーの権限を尊重する必要があります。

このフレームワークをサポートするために、Databricks Apps は 2 つの補完的な ID モデルを使用します。

• アプリの承認 により、一貫性のあるアクセス許可セットを持つ独自の ID がアプリに与えられます。
• ユーザー承認 を使用すると、アプリは、それを操作するユーザーの ID とアクセス許可を使用できます。

アプリの承認

各Azure Databricks アプリには専用の service principal があり、リソースAzure Databricksアクセスするときに ID として機能します。 このサービス プリンシパルはアプリ インスタンスに固有であり、アプリ間で再利用することはできません。 アプリに割り当てられているサービス プリンシパルを変更したり、アプリの作成時に既存のサービス プリンシパルを指定したりすることはできません。 Azure Databricksはこのアイデンティティを使って、ユーザーの関与とは独立してアプリの権限を評価するため、アプリはユーザーインタラクションの文脈外でも明示的に付与されたリソースのみにアクセスできます。

この分離により、アプリ間のセキュリティ境界が強化されます。 また、アプリのアクティビティを監査可能にし、バックグラウンド処理や自動化タスクなどのシナリオもサポートします。

サービス プリンシパルは、一意の ID で表されます。 アプリの [承認 ] タブからコピーします。

アプリを作成すると、Azure Databricksはアプリの専用サービス プリンシパルを自動的にプロビジョニングします。 サービス プリンシパルは、アプリのすべてのデプロイで同じままです。 アプリを削除すると、Azure Databricks がサービス プリンシパルを削除します。

個々のユーザーのコンテキストを必要とせずに、アプリが単独で実行するアクションにはサービス プリンシパルを使用します。 一般的な使用用途は次のとおりです。

• バックグラウンド タスクの実行
• 共有構成またはメタデータの読み取りまたは書き込み
• アクティビティまたは使用状況メトリックのログ記録
• セキュリティで保護されたエンドポイントを介した外部サービスの呼び出し

アプリによって開始されるすべてのアクションは、サービス プリンシパルのアクセス許可を使用します。 標準のアクセス許可の割り当てを使用して、サービス プリンシパルに特定のリソースへのアクセス権を付与します。 ただし、ユーザー レベルのアクセス制御はサポートされていません。 アプリを操作するすべてのユーザーは、サービス プリンシパルに対して定義されているのと同じアクセス許可を共有します。これにより、アプリは個々のユーザー ID に基づいてきめ細かいポリシーを適用できなくなります。

次の例は、アプリがサービス プリンシパルを使用して Unity カタログ内のデータを照会する方法を示しています。

この場合、サービス プリンシパルは、SQL ウェアハウスとクエリする Unity カタログ テーブルの両方に明示的にアクセスする必要があります。

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

アプリの認証情報を取得する

アプリの承認のために、Azure Databricksはサービス プリンシパルの資格情報をアプリの環境に自動的に挿入します。 次の環境変数は、必要な OAuth クライアント値を保持します。

Azure Databricksは、アプリ ランタイムで環境変数を自動的に設定します。 アプリは、それ自体として認証するときにこれらの変数を使用します。

Python

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

JavaScript

const clientId = process.env.DATABRICKS_CLIENT_ID;
const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;

例:アプリ認証付きクエリ

Python

この例では、環境変数からサービス プリンシパルの資格情報をプルし、OAuth 承認を実行する SDK Config オブジェクトを使用します。

from databricks import sql
from databricks.sdk.core import Config

cfg = Config()

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    credentials_provider=lambda: cfg.authenticate,
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

この例では、環境変数を使用して OAuth を使用してサービス プリンシパルで認証し、 Databricks SQL Driver for Node.jsでクエリを実行します。

import { DBSQLClient } from '@databricks/sql';

const client = new DBSQLClient();

const connection = await client.connect({
  authType: 'databricks-oauth',
  host: process.env.DATABRICKS_SERVER_HOSTNAME,
  path: process.env.DATABRICKS_HTTP_PATH,
  oauthClientId: process.env.DATABRICKS_CLIENT_ID,
  oauthClientSecret: process.env.DATABRICKS_CLIENT_SECRET,
});

const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
const cursor = await connection.cursor(query);

const rows = [];
for await (const row of cursor) {
  rows.push(row);
}

console.log(rows.slice(0, 5)); // Like df.head()

await connection.close();

ユーザーの承認

ユーザー承認は、ユーザーの 代理承認とも呼ばれ、Databricks Apps アプリがアプリ ユーザーの ID で動作することを許可します。 Azure Databricksは、ユーザーのアクセス トークンをアプリに転送します。このトークンを使用して、ユーザーの代わりにリソースにアクセスします。 Azure Databricksは、ユーザーの既存の Unity Catalog ポリシーに基づいてすべてのアクセス許可を適用します。

ユーザーの代わりに動作するアプリのセキュリティ リスクを管理するために、Azure Databricksはスコープを使用して、アプリがユーザーの承認によって実行できるアクションを制限します。

アプリが個々のユーザーのアクセス許可を尊重する必要がある場合は、ユーザー承認を適用します。 一般的なユース ケースは次のとおりです。

• テーブルまたはボリュームのクエリ
• SQL ウェアハウスまたはコンピューティングへのアクセス
• ユーザー アクションに関連付けられたジョブまたはワークフローの実行

すべてのアクションでは、ユーザーの既存の Unity カタログアクセス許可が使用されます。

ユーザー承認では、行レベルのフィルターや列マスクなどの Unity カタログ機能をアプリ アクティビティに適用することで、きめ細かいアクセス制御が可能になります。 このアプローチでは、アクセス制御とワークスペース ガバナンスの一貫性が保たれ、アクセス許可ロジックがアプリにハードコーディングされるのを回避できます。

ユーザー認可によるきめ細かな権限設定

アプリにユーザー承認を追加すると、次のようなユーザーの既存の Unity カタログアクセス許可が適用されます。

• 表示される行を制限する行レベルのフィルター
• 列マスクを使用して機密データを編集または変換する

Azure Databricksはユーザーの ID を使用してユーザー承認要求を評価するため、これらのポリシーはアプリがデータにアクセスするときに自動的に適用されます。 たとえば、テーブルにリージョン別の可視性を制限する行フィルターが含まれている場合、アプリはユーザーがクエリを実行できる行のみを返します。 アプリで追加のフィルター処理ロジックは必要ありません。

この方法では、アプリケーション コードでアクセス制御ロジックを複製することを回避し、ワークスペース レベルのガバナンスとの一貫性を確保します。 管理者が Unity カタログ ポリシーを更新すると、アプリはこれらの変更を自動的に考慮します。

スコープベースのセキュリティと特権のエスカレーション

ユーザー承認を使用するアプリでは、ユーザーに代わってアプリが実行できる操作を制限するために、特定の承認スコープを宣言する必要があります。 スコープは、次のような特定の API またはリソースの種類へのアクセスを制限します。

• sql SQL ウェアハウスに対してクエリを実行する場合
• Genie エージェントを管理するための genie
• files ファイルとディレクトリを管理するための

スコープを選択しない場合、Azure Databricksは、アプリが基本的なユーザー ID 情報を取得できるようにする既定のセットを割り当てます。

• iam.access-control:read
• iam.current-user:read

これらの既定値は、ユーザー承認機能をサポートするために必要ですが、データやコンピューティング リソースへのアクセスは許可されません。 アプリを作成または編集するときに、スコープを追加します。

スコープでは、最小権限ポリシーに従います。 必要なスコープのみを要求するようにアプリを構成してください。 Azure Databricksは、ユーザーがアクセス許可を持っている場合でも、承認されたスコープ外のすべての機能へのアクセスをブロックします。 たとえば、アプリが sql スコープのみを要求した場合、ユーザーがアプリの外部にアクセスできる場合でも、エンドポイントを提供するモデルにアクセスすることはできません。

ユーザーが初めてアプリにアクセスすると、Azure Databricksは各要求されたスコープ内で動作する権限をアプリに付与するよう促します。 同意を付与した後、ユーザーはそれを取り消すことはできません。 管理者は、必要に応じて、組織のポリシーに合わせてアクセスを調整するために、ユーザーに代わって同意を付与できます。

アプリにスコープを追加する

Azure Databricks UIまたはDatabricks CLIで認可スコープを追加してください。

UI

Azure Databricks UI でアプリを作成または編集するときに、ユーザー承認を構成します。

[ユーザーの承認で、 + スコープの追加をクリックし、アプリがユーザーの代わりにアクセスできる API またはリソースAzure Databricks定義するスコープを選択します。 Azure Databricksは実行時にこれらのスコープを適用し、アクセス権を付与する前にユーザーまたは管理者の同意が必要です。

CLI

アプリを作成または更新する際は、user_api_scopes を指定します:

databricks apps create <app-name> \
  --json '{
    "user_api_scopes": ["sql", "files"]
  }'

databricks apps create-update <app-name> \
  --json '{
    "update_mask": "user_api_scopes",
    "app": {
      "user_api_scopes": ["sql", "files"]
    }
  }'

完全な例については、GitHub の Databricks Apps 承認デモを参照してください。 アプリの例では、アプリとユーザー承認モデルの両方を使用する方法を示し、セットアップ手順とユーザー承認を使用したクエリの例が含まれています。

サポートされているスコープ

Azure Databricks Apps は以下の Azure Databricks API スコープをサポートしています:

• ai-gateway
• apps
• files
• genie
• model-serving
• postgres
• sql
• vector-search
• sql:restricted-query (読み取り専用SQLクエリを実行する)

Azure Databricks Apps は以下のSDKスコープもサポートしています。 これらのスコープは :read 修飾子を使って GET エンドポイントへのアクセスを制限できます。

• catalog.catalogs
• catalog.connections
• catalog.schemas
• catalog.tables
• workspace.workspace

以下のスコープは廃止されています。 代わりに現在のスコープを使いましょう。

ユーザー承認スコープを制限する

ワークスペース管理者は、アプリ開発者がワークスペース内のアプリに追加できる OAuth スコープを制御できます。

UI

1. Azure Databricks ワークスペースの上部バーでユーザー名をクリックし、[設定] を選択します。
2. [ 開発] をクリックします。
3. [ アプリ] で、 アプリの OAuth スコープを選択した値に制限する設定を 見つけて、許可リストを構成します。
4. ページを更新して変更を有効にします。

デフォルト値は 「All API」であり、 すべてのサポート可能なスコープを許可します。 [なし] を選択すると、ユーザーの承認が無効になります。

CLI

DatabricksのCLIを使ってスコープの許可リストを取得したり更新したりしてください。

現在の設定を得るには:

databricks workspace-settings-v2 get-public-workspace-setting allowedAppsUserApiScopes

具体的な許容範囲を設定するには:

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["sql", "files"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

すべてのスコープを許可するには(デフォルト):

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["*"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

ユーザー認証を無効にするには、 allowed_scopes を空の配列([])に設定してください。

アカウント管理者は、それらのスコープがワークスペースの許可リストにない場合でも、アプリにスコープを追加できます。

ユーザー認証情報を取得

ユーザー承認Azure Databricks、ユーザーの ID とアクセス トークンを HTTP ヘッダー内のアプリに転送します。 アプリは、ユーザーの代わりに動作するために、これらのヘッダーを抽出する必要があります。

これらのヘッダーを取得する方法は、使用するフレームワークによって異なります。

Streamlit

import streamlit as st
user_access_token = st.context.headers.get('x-forwarded-access-token')

Gradio

import gradio as gr

def query_fn(message, history, request: gr.Request):
    access_token = request.headers.get("x-forwarded-access-token")
    ...

パラメーターとして宣言すると、Gradio によって要求オブジェクトがアプリの関数に自動的に挿入されます。 要求を手動で構築または取得する必要はありません。

ダッシュとフラスク

from flask import request

headers = request.headers
user_token = headers.get('x-forwarded-access-token')

Shiny

user_token = session.http_conn.headers.get('x-forwarded-access-token')

簡易

import express from 'express';

const userAccessToken = req.header('x-forwarded-access-token');

例:ユーザー承認付きクエリ

この場合、アプリはユーザーのアクセス トークンをコネクタに直接渡し、Azure Databricksはユーザーのアクセス許可をクエリに適用します。

Python

from databricks import sql
from databricks.sdk.core import Config
from flask import request

cfg = Config()
user_token = request.headers.get("x-forwarded-access-token")

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    access_token=user_token
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

import { DBSQLClient } from '@databricks/sql';
import express from 'express';

const app = express();

app.get('/', async (req, res) => {
  const userToken = req.header('x-forwarded-access-token');

  const client = new DBSQLClient();
  const connection = await client.connect({
    authType: 'access-token',
    host: process.env.DATABRICKS_SERVER_HOSTNAME,
    path: process.env.DATABRICKS_HTTP_PATH,
    token: userToken,
  });

  const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
  const cursor = await connection.cursor(query);

  const rows = [];
  for await (const row of cursor) {
    rows.push(row);
  }

  console.log(rows.slice(0, 5));
  await connection.close();

  res.send('Query complete');
});

app.listen(3000);

ユーザー認証のベストプラクティス

ユーザーに代わってアクションを実行するアプリを構築する場合は、次のベスト プラクティスに従って、セキュリティで保護された監査可能なアクセスを確保します。

• アプリの所有者または少数の信頼されたユーザーのみがアクセスできるフォルダーにアプリ コードを格納します。
• アプリのメンテナンスとレビューを担当する信頼できる上級開発者にのみ、 CAN MANAGE アクセス許可を付与します。 アプリの実行が承認された特定のユーザーまたはグループにのみ、 CAN USE アクセス許可を付与します。
• トークンを印刷したり、ログに記録したり、ファイルに書き込んだりしないでください。 これは、すべてのログ 記録ステートメント、デバッグ ツール、およびエラー ハンドラーに適用されます。 たとえば、print(f"User token: {token}")の代わりにheaders = {"Authorization": f"Bearer {token}"}を使用します。
• 機能に必要な最低限必要な承認スコープのみを要求するように各アプリを構成します。
• コード レビュー中に、スコープとアクセス許可の設定がセキュリティ要件と一致し、不要なアクセス権を付与していないことを確認します。
• 運用環境にデプロイする前に、すべてのアプリ コードに対してピア レビューを適用します。
• ユーザーのためにアプリが行うすべてのアクションについて、ユーザーID、アクションタイプ、ターゲットリソース、ステータスなどの構造化された監査ログを記録します。

認証方法

Databricks Apps のトークンを取得するために、ユーザーとサービス プリンシパルの両方が標準の OAuth 2.0 フローを使用して認証されます。 メソッドは、呼び出し元がユーザーであるか、自動化されたワークロードであるかによって異なります。

ワークスペース ログインの場合 (ユーザーのみ):

• シングル サインオン (SSO): シングル サインオン (SSO) が構成されている場合、ユーザーは ID プロバイダーを介して認証を行います。
• ワンタイム パスワード (OTP): SSO が構成されていない場合、ユーザーは一時的なパスワードを受け取ります。

OAuth フロー (アプリとワークロード) の場合:

• ユーザーからマシンへの (U2M) OAuth: ユーザーが認証され、結果のトークンによってユーザー承認が有効になり、アプリがユーザーの代わりに動作できるようになります。
• マシン間 (M2M) OAuth: サービス プリンシパルは、クライアント資格情報またはフェデレーションを使用して認証します。 これらのトークンは、アプリがユーザーではなくそれ自体として機能するアプリの承認を支えます。

トークン認証を使用して Databricks アプリを呼び出す手順については、「トークン認証を 使用して API Databricks アプリに接続する」を参照してください。

モデルの比較と結合

Databricks Apps では、アプリとユーザーの承認を個別に、またはまとめて使用できます。 これらのモデルはさまざまな目的に対応し、並列で動作するように設計されています。