Databricks アプリで認可の設定をする
Databricks Apps の認可モデルは OAuth 2.0 に基づいており、アプリに割り当てられた権限と、アプリにアクセスするユーザーの権限が組み合わされます。アプリはワークスペース内のデータやサービスにアクセスするため、データアクセス制御を適用し、ユーザーの権限を尊重する認証および認可を使用する必要があります。
このフレームワークをサポートするために、Databricks Apps では 2 つの補完的な ID モデルを使用します。
アプリの認可
各 Databricks アプリには、Databricks リソースにアクセスする際に ID として機能する専用の Service Principal があります。この Service Principal はアプリ インスタンス固有のものであり、アプリ間で再利用することはできません。アプリに割り当てられた Service Principal を変更したり、アプリの作成中に既存の Service Principal を指定したりすることはできません。Databricks はこの ID を使用して、ユーザーとは独立してアプリの権限を評価するため、ユーザーの操作のコンテキスト外であっても、アプリは明示的に許可されたリソースにのみアクセスできます。
この分離により、アプリ間のセキュリティ境界が強制されます。また、アプリのアクティビティを監査可能にし、バックグラウンド処理や自動化タスクなどのシナリオをサポートします。
サービスプリンシパルは一意のIDで表されます。 アプリの 承認 タブからコピーします:
アプリを作成すると、 Databricks 自動的にプロビジョニング専用のサービスプリンシパルが発行されます。 サービスプリンシパルは、アプリのすべてのデプロイで同じままです。 アプリを削除すると、サービスプリンシパル Databricks 削除されます。
サービスプリンシパルは、個々のユーザーのコンテキストを必要とせずに、アプリが独自に実行するアクションに使用します。 一般的な使用例は次のとおりです。
- バックグラウンドタスクの実行
- 共有構成またはメタデータの読み取りまたは書き込み
- アクティビティまたは使用状況のメトリクスのロギング
- セキュアなエンドポイントを介した外部サービスの呼び出し
アプリによって開始されるすべてのアクションは、サービスプリンパルシの権限を使用します。 標準の権限割り当てを使用して、サービスプリンシパルに特定のリソースへのアクセスを付与します。 ただし、ユーザー レベルのアクセス制御はサポートされていません。アプリを操作するすべてのユーザーは、サービスプリンシパルに定義された同じ権限を共有します。これにより、アプリは個々のユーザー ID に基づいて詳細なポリシーを適用することができなくなります。
次の例は、アプリがサービスプリンシパルを使用して Unity Catalog内のデータをクエリする方法を示しています。
この場合、サービスプリンシパルは、 SQLウェアハウスとクエリを実行する Unity Catalog テーブルの両方に明示的にアクセスする必要があります。
このモデルは、アプリのすべてのユーザーに同じデータを表示する場合や、アプリがユーザー固有のアクセス制御に関連付けられていない共有操作を実行する場合に適しています。
アプリの認証資格情報の取得
アプリの認可の場合、 Databricks はサービスのプリンシパル資格情報をアプリの環境に自動的に挿入します。 次の環境変数は、必要な OAuth クライアント値を保持します。
変数 | 説明 |
|---|---|
| サービスプリンシパルのOAuth クライアント ID |
| サービスプリンシパルのOAuthクライアントシークレット |
Databricks は、アプリ ランタイムで環境変数を自動的に設定します。アプリは、それ自体として認証するときにこれらの変数を使用します。
- Python
- JavaScript
import os
client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')
const clientId = process.env.DATABRICKS_CLIENT_ID;
const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;
Databricks SDK を使用している場合、通常、これらの環境変数に手動でアクセスする必要はありません。SDK は 統合認証 に従い、環境内の資格情報を自動的に検出します。
例: アプリの認可を使用したクエリー
- Python
- JavaScript
この例では、 SDK Config オブジェクトを使用して、環境変数からサービスプリンシパル の資格情報 を取得し、 OAuth 認証を実行します。
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()
この例では、環境変数を使用して 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 で動作できます。Databricks はユーザーのアクセス トークンをアプリに転送し、アプリはトークンを使用してユーザーに代わってリソースにアクセスします。Databricks は、ユーザーの既存の Unity Catalog ポリシーに基づいてすべてのアクセス許可を適用します。
ユーザーに代わって動作するアプリのセキュリティリスクを管理するために、Databricks はスコープを使用して、ユーザーが認可を通じて実行できるアクションを制限します。
アプリが個々のユーザー権限を尊重する必要がある場合は、ユーザー認可を適用します。一般的な使用例は次のとおりです。
- テーブルまたはボリュームのクエリ
- SQLウェアハウスまたはコンピュートへのアクセス
- ユーザーアクションに関連付けられたジョブまたはワークフローの実行
すべてのアクションでは、ユーザーの既存の Unity Catalog のアクセス許可が使用されます。
ユーザー認可では、行レベルのフィルターや列マスクなどの Unity Catalog の機能をアプリのアクティビティに適用することで、きめ細かなアクセス制御が可能になります。このアプローチにより、アクセス制御とワークスペースのガバナンスとの一貫性が保たれ、アクセス許可ロジックがアプリにハードコーディングされるのを回避できます。
ユーザー認可によるきめ細かな権限
アプリにユーザー認可を追加すると、次のようなユーザーの既存の Unity Catalog のアクセス許可が適用されます。
- 表示される行を制限する行レベルのフィルター
- 機密データを編集または変換するための列マスク
Databricks はユーザーの ID を使用してユーザー認可要求を評価するため、アプリがデータにアクセスすると、これらのポリシーが自動的に適用されます。たとえば、テーブルに地域ごとに表示を制限する行フィルターが含まれている場合、アプリはユーザーがクエリを許可された行のみを返します。アプリには追加のフィルタリングロジックは必要ありません。
このアプローチにより、アプリケーション コード内のアクセス制御ロジックの重複が回避され、ワークスペース レベルのガバナンスとの一貫性が確保されます。管理者が Unity Catalog ポリシーを更新すると、アプリは自動的にその変更を尊重します。
スコープベースのセキュリティと特権昇格
ユーザー認証を使用するアプリは、ユーザーに代わってアプリが実行できる操作を制限するために、特定の認証スコープを宣言する必要があります。スコープは、次のような特定のAPIsまたはリソース タイプへのアクセスを制限します。
sqlクエリ用 SQLウェアハウスgenieGenie エージェントを管理するためのfilesファイルやディレクトリの管理のため
スコープを選択しない場合、 Databricksアプリが基本的なユーザー ID 情報を取得できるようにするセットを割り当てます。
iam.access-control:readiam.current-user:read
これらはユーザー認証機能をサポートするために必要ですが、データやコンピュート リソースへのアクセスは許可しません。 アプリを作成または編集するときに、追加のスコープを追加します。
スコープは最小権限の原則を適用します。必要なスコープのみを要求するようにアプリを構成するようにしてください。Databricks は、ユーザーが権限を持っている場合でも、承認されたスコープ外の機能へのアクセスをブロックします。たとえば、アプリがsqlスコープのみをリクエストする場合、ユーザーがアプリの外部でアクセスできたとしても、モデルサービング エンドポイントにアクセスすることはできません。
ユーザーが初めてアプリにアクセスすると、Databricks は要求された各スコープ内でアプリが動作するための許可を付与するようユーザーに求めます。同意を付与した後、ユーザーはそれを取り消すことができません。管理者は、組織のポリシーに合わせてアクセスを調整するために、ユーザーに代わって同意を付与することができます。
アプリにスコープを追加する
Databricks UI または Databricks CLI を使用して、認証スコープを追加します。
- UI
- CLI
Databricks UI でアプリを作成または編集するときに、ユーザー認証を構成します。
「ユーザー認証」 で 「+スコープを追加」 をクリックし、どのDatabricks APIsまたは アプリがユーザーに代わってアクセスできるかを定義するスコープを選択します。 Databricksはこれらのスコープをランタイム時に強制し、アクセスを許可する前にユーザーまたは管理者の同意を必要とします。
アプリを作成または更新するときに 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 認可デモを参照してください。サンプル アプリでは、アプリとユーザーの両方の認可モデルの使用方法を示し、ユーザー認可を使用したセットアップ手順とクエリの例が含まれています。
サポートされているスコープ
Databricks Apps は、以下の Databricks API スコープをサポートしています。
ai-gatewayappsfilesgeniemodel-servingpostgressqlvector-searchsql:restricted-query（読み取り専用のSQLクエリーを実行）
Databricks Appsは、以下の SDK スコープもサポートしています。これらのスコープは、:read修飾子を使用してGET Endpointへのアクセスを制限できます。
次のスコープは非推奨です。代わりに現在のスコープを使用してください。
非推奨のスコープ | 現在のスコープ |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ユーザー認証範囲を制限する
ワークスペース管理者は、アプリ開発者がワークスペース内のアプリに追加できるOAuthスコープを制御できます。
- UI
- CLI
- Databricksワークスペースの上部のバーにあるユーザー名をクリックし、 [設定] を選択します。
- 「開発」 をクリックします。
- 「アプリ」 の下にある 「アプリのOAuthスコープを選択した値に制限する」設定を 見つけて、許可リストを設定します。
- 変更を反映させるには、ページを更新してください。
デフォルト値は All APIs であり、これによりすべての サポートされているスコープ が許可されます。 None を選択すると、ユーザー認可が無効になります。
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"
}'
すべてのスコープを許可するには (default):
databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
--json '{
"allowed_apps_user_api_scopes": {
"allowed_scopes": ["*"]
},
"name": "allowedAppsUserApiScopes"
}'
ユーザー認可を無効にするには、allowed_scopes を空の配列 ([]) に設定します。
アカウント管理者は、ワークスペースの許可リストに含まれていないスコープであっても、アプリにスコープを追加できます。
既に実行中のアプリは、既存のスコープで引き続き実行されます。許可されていないスコープを削除するまで、アプリの起動、デプロイ、または更新はできません。
ユーザー認可資格情報の取得
ユーザー認可の場合、Databricks はユーザーの ID とアクセス トークンを HTTP ヘッダーでアプリに転送します。アプリは、ユーザーに代わって動作するために、これらのヘッダーを抽出する必要があります。
これらのヘッダーを取得する方法は、使用するフレームワークによって異なります。
- Streamlit
- Gradio
- Dash and Flask
- Shiny
- Express
import streamlit as st
user_access_token = st.context.headers.get('x-forwarded-access-token')
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')
user_token = session.http_conn.headers.get('x-forwarded-access-token')
import express from 'express';
const userAccessToken = req.header('x-forwarded-access-token');
例: ユーザー認可を使用したクエリー
この場合、アプリはユーザーのアクセス トークンを直接コネクタに渡し、Databricks はユーザーのアクセス許可をクエリに適用します。
- Python
- JavaScript
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()
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アクセス許可を付与します。- トークンを印刷、log、またはファイルに書き込まないでください。これは、すべてのログステートメント、デバッグツール、およびエラーハンドラーに適用されます。たとえば、
print(f"User token: {token}")の代わりにheaders = {"Authorization": f"Bearer {token}"}を使用します。 - 各アプリは、その機能に必要な最小限の認可スコープのみを要求するように構成します。
- コード レビュー中に、スコープとアクセス許可の設定がセキュリティ要件と一致していること、および不要なアクセスを許可していないことを確認します。
- 本番運用環境にデプロイする前に、すべてのアプリコードに対してピアレビューを実施します。
- ユーザーID、アクションタイプ、ターゲットリソース、ステータスなど、アプリがユーザーの代わりに行うすべてのアクションについて、構造化された監査Logsを記録します。
認証方法
Databricks Apps のトークンを取得するには、ユーザーとサービス プリンシパルの両方が標準のOAuth 2.0 フローを使用して認証します。 方法は、呼び出し元がユーザーであるか、自動化されたワークロードであるかによって異なります。
ワークスペースログインの場合（ユーザーのみ）：
- シングル サインオン (SSO): シングル サインオン (SSO) が構成されている場合、ユーザーは ID プロバイダーを通じて認証します。
- ワンタイム パスワード (OTP): SSO が構成されていない場合、ユーザーは一時パスワードを受け取ります。
OAuth フロー (アプリとワークロード) の場合:
- ユーザー対マシン (U2M) OAuth : ユーザーが認証し、結果として得られるトークンによってユーザー承認が有効になり、アプリがユーザーに代わって動作できるようになります。
- マシンツーマシン (M2M) OAuth : サービス プリンシパルは、クライアントの資格情報またはフェデレーションを使用して認証します。 これらのトークンは、アプリがユーザーではなくアプリ自身として機能するアプリ認証の基盤となります。
トークン認証を使用して Databricks アプリを呼び出す手順については、 「トークン認証を使用して API Databricks アプリに接続する」を参照してください。
モデルの比較と結合
Databricks アプリは、アプリとユーザーの認可を個別に使用することも、一緒に使用することもできます。これらのモデルは異なる目的を果たし、並行して動作するように設計されています。
認可モデル | いつ使用するか | 使用例 |
|---|---|---|
アプリ認可 | アプリがユーザーの ID に依存しない操作を実行する場合 | ログの書き込み、共有設定へのアクセス、外部サービスの呼び出し |
ユーザー認可 | アプリが現在のユーザーのコンテキストでリソースにアクセスする必要がある場合 | Unity Catalogデータのクエリ、コンピュートの起動、行レベルの権限の適用 |
両方 | アプリが共有操作とユーザー固有の操作の両方を実行する場合 | アプリ ID によるメトリクスのログ記録、ユーザー ID によるフィルター処理されたデータのクエリ |