Unity Catalogのシークレット
Unity Catalogシークレットは、パスワード、トークン、APIキーなどの機密認証情報を格納するセキュア保護オブジェクトです。シークレットは3段階の名前空間(catalog.schema.secret)を使用し、メタストアに接続されているすべてのワークスペースで利用できます。
他のデータ資産と同じ Unity Catalog 特権でシークレットを管理でき、個々のシークレットまで細かく管理できます。ユーザーはシークレットを読み取ったり使用したりせずに閲覧したり、独自のキーでシークレット値を暗号化したりできます。また、監査 Logs ですべての読み取りや変更が記録されます。
要件
- ワークスペースで Unity Catalog が有効になっている必要があります。Unity Catalog とはを参照してください。
dbutilsでシークレットを読み取るには、環境バージョン4以降でServerlessノートブックとジョブを使用するか、Databricks Runtime 17.3 LTS以降を実行するクラシックコンピュートを使用します。Databricksでは、Serverlessまたは標準アクセス モードの使用を推奨しています。- UDFでシークレットを使用するには、UDFでシークレットを使用をご覧ください。
シークレットを作成します
シークレットはスキーマに保存されます。必要なプリンシパルのみがアクセスできるスキーマにシークレットを作成します。シークレットを必要とするユーザーごとにスキーマにグループ化する方法については、必要とするユーザーごとにシークレットをグループ化するをご覧ください。
Databricks マネージドシークレットを作成する
Databricks 管理シークレットを作成するには、カタログに対する USE CATALOG と、スキーマの所有権、またはそれに対する CREATE SECRET と USE SCHEMA が必要です。
アプリケーションのシークレットのスキーマを作成するには、以下をランします:
CREATE SCHEMA IF NOT EXISTS main.orders_app;
- Catalog Explorer
- REST API
- Databricks ワークスペースで、 カタログ をクリックしてカタログ エクスプローラを開きます。
- シークレットを作成するスキーマに移動します。
- 作成 > シークレット をクリックします。
- 名前 と 値 を入力します。オプションで、 コメント と 有効期限 を追加します。シークレットの有効期限が切れると、カタログエクスプローラに警告が表示されます。
- 作成 をクリックします。
シークレットを作成するには、以下をラン:
curl -X POST \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"catalog_name": "main",
"schema_name": "orders_app",
"name": "db_password",
"value": "your_secret_value",
"comment": "Password for the orders database"
}' \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"
シークレットへのアクセス権の付与
各プリンシパルが必要とする操作に一致する権限を付与します。BROWSE の場合を除き、すべてのプリンシパルは、親カタログとスキーマで USE CATALOG と USE SCHEMA も必要とします。カタログまたはスキーマに付与された権限は、後で作成されたシークレットを含む、その中のシークレットに適用されます。
プリンシパルに許可するには | 付与 |
|---|---|
ノートブック、ジョブ、または REST API 呼び出しで値を読み取ります |
|
値を確認せずに特定のシークレットを検出する |
|
値を更新 |
|
スキーマにシークレットを作成する |
|
シークレットに対する権限を他のユーザーに付与する | シークレット、スキーマ、またはカタログの所有権、または |
特権を付与するには、カタログエクスプローラーを使用します。シークレットまたはスキーマを開き、「 パーミッション」(Permissions ) tabをクリックして、「 付与」(Grant ) をクリックします。SQL で付与するには、次のコマンドを実行します:
-- Let a job's service principal read every secret in a schema
GRANT USE CATALOG ON CATALOG main TO `etl-service-principal`;
GRANT USE SCHEMA, READ SECRET ON SCHEMA main.orders_app TO `etl-service-principal`;
-- Let the application's developers create secrets in its schema
GRANT USE SCHEMA, CREATE SECRET ON SCHEMA main.orders_app TO `orders-developers`;
Unity Catalog での特権の管理を参照してください。
シークレットの読み込み
シークレット値を読み取るには、シークレットの所有権、またはシークレット、あるいはそのスキーマやカタログに対する READ SECRET が必要です。
- Secrets utility (dbutils.secrets)
- REST API
Databricksはdbutilsを使用することを推奨します。これはセル出力とLogs内の値を編集するためです。次の例では、データベースのユーザー名とパスワードを読み取ってJDBC読み取りを構成します。
username = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_username")
password = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_password")
df = (spark.read
.format("jdbc")
.option("url", "<jdbc-url>")
.option("dbtable", "<table-name>")
.option("user", username)
.option("password", password)
.load()
)
シークレットユーティリティ(dbutils.secrets)をご覧ください。
Unity Catalog REST API は、返された値を編集しません。監査 Logs は引き続き各読み取りを記録します。Databricks では、代わりに dbutils を使用することをお勧めします。
値を返すには、include_value=trueを設定し、応答のeffective_valueフィールドを読み込みます。
curl -G \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
--data-urlencode "include_value=true" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password"
シークレットの一覧表示、更新、削除
値を更新するには、シークレットに対するWRITE SECRETが必要です。コメントや有効期限を変更したり、削除したりするには、シークレット、そのスキーマ、またはそのカタログに対する所有権またはMANAGEが必要です。
- Catalog Explorer
- Secrets utility (dbutils.secrets)
- REST API
- カタログエクスプローラーでスキーマに移動し、 [概要] ペインの [シークレット] をクリックしてシークレットを一覧表示します。
- 変更するシークレットをクリックします。
- 右上隅で、ケバブメニュー(縦に3つ並んだドット)をクリックし、 Edit または Delete を選択します。
- 編集するには、新しい値または有効期限を入力し、 確認 をクリックします。削除するには、シークレットの完全な名前を入力し、 削除 をクリックします。
スキーマ内でアクセスできるシークレットを一覧表示するには、次をランします。
all_secrets = dbutils.secrets.list(catalog="main", schema="orders_app")
シークレットを一覧表示するには、以下をランします。さらに結果がある場合は、レスポンスの next_page_token を page_token として渡します:
curl -G \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
--data-urlencode "catalog_name=main" \
--data-urlencode "schema_name=orders_app" \
--data-urlencode "page_size=100" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"
値を更新するには、以下をランします。update_maskとリクエストボディの両方に含まれるフィールドのみが変更されます:
curl -X PATCH \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"value": "new_secret_value"}' \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password?update_mask=*"
シークレットを削除するには、次をラン:
curl -X DELETE \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
"$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password"
シークレットアクセスを監査する
system.access.audit システムテーブルはシークレットイベントを記録します。読み取りはaction_name = 'getSecret'で表示されます。過去7日間のシークレットイベントをリストするには、次のコマンドを実行します。
SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE service_name = 'unityCatalog'
AND action_name LIKE '%Secret%'
AND event_date >= current_date() - INTERVAL 7 DAYS
ORDER BY event_time DESC;
監査ログシステムテーブルリファレンスを参照してください。
顧客管理キーを使用してシークレット値を暗号化する
Databricksは、defaultでDatabricksマネージドキーを使用してシークレット値を暗号化します。独自のキーを使用するには、シークレットを保持するカタログで顧客マネージドキー(CMK)設定を構成します。シークレット値はカタログのストレージの場所ではなくUnity Catalogに格納されるため、外部ストレージの場所を持つものを含むすべてのカタログで機能します。要件とセットアップについては、「Unity Catalog の顧客マネージドキー」を参照してください。
UDF でシークレットを使用する
Unity Catalog PythonまたはScala UDFは、呼び出し元にシークレットへのアクセス権を与えずにシークレット値を使用できます。UDFのSECRETS句でシークレットを宣言します。UDF は、関数所有者の権限で読み取ります。
- 所有者は、UDF を作成または置き換えるためにシークレットに対する
READ SECRETを必要とします。所有者がREAD SECRETを失った場合、UDF は失敗します。 - 呼び出し元は UDF に対する
EXECUTEのみを必要とし、シークレットに対する権限は必要ありません。
UDF定義は、environment_versionを6以上に設定する必要があります。クラシックコンピュートでは、Databricks Runtime 19以降の標準アクセスモードを使用してください。例については、Python UDFsおよびScala UDFsを参照してください。
セッションスコープのUDF(databricks.secrets.get()またはcom.databricks.Secrets.get()を使用)は呼び出し元の権限でシークレットを読み取るため、すべての呼び出し元にREAD SECRETが必要です。Python UDFとScala UDFを参照してください。
専用アクセスモードのコンピュートでは、これらの UDF を直接呼び出すことはできません。属性ベースのアクセス制御(ABAC)列マスクとして使用する Unity Catalog SQL 関数から、この関数を呼び出すことができます。これは Databricks が serverless コンピュートで強制します。サポートされていないコンピュートバージョンを参照してください。
シークレット値は UDF 内でのみ使用してください。UDF の結果でそれらを返さないでください。Redaction は、エラーや Logs での偶発的な露出を減らしますが、UDF コードがクエリー結果でシークレットを返すことを防ぐものではありません。
制限事項
- クォータ : スキーマは最大 1,000 個のシークレットを保持でき、メタストアは最大 10,000 個まで保持できます。
- グローバル検索または情報schemaなし : シークレットは、グローバル検索または情報schemaテーブルには表示されません。Catalog Explorer、
dbutils、または REST API を使用します。 - OAuth APIスコープ :Unity Catalog Secrets APIには、
unity-catalogOAuth APIスコープが必要です。secretsスコープは、ワークスペースのSecret Scopeにのみ適用されます。 - Initスクリプト :グローバルまたはクラスタースコープのinitスクリプトでUnity Catalogシークレットを使用することはできません。
- リモート開発 :
dbutils.secretsにはDatabricks Runtimeでバックアップされたノートブックまたはジョブが必要なため、Databricks Connectおよびコンパイル済みJARランモードはUnity Catalogシークレットを読み取れません。
その他のリソース
-
- Unity Catalog シークレットのベストプラクティス
- 環境、アプリケーション、またはチームごとにシークレットを整理し、ワークロードがシークレットを読み取ることなくシークレットを使用できるようにします。
-
- シークレット管理
- Unity CatalogのシークレットとワークスペースのSecret Scopeを比較し、それぞれを使用できる場所をご確認ください。