メインコンテンツまでスキップ

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 が必要です。

アプリケーションのシークレットのスキーマを作成するには、以下をランします:

SQL
CREATE SCHEMA IF NOT EXISTS main.orders_app;
  1. Databricks ワークスペースで、 カタログ をクリックしてカタログ エクスプローラを開きます。
  2. シークレットを作成するスキーマに移動します。
  3. 作成 > シークレット をクリックします。
  4. 名前 と 値 を入力します。オプションで、 コメント と 有効期限 を追加します。シークレットの有効期限が切れると、カタログエクスプローラに警告が表示されます。
  5. 作成 をクリックします。

シークレットへのアクセス権の付与​

各プリンシパルが必要とする操作に一致する権限を付与します。BROWSE の場合を除き、すべてのプリンシパルは、親カタログとスキーマで USE CATALOG と USE SCHEMA も必要とします。カタログまたはスキーマに付与された権限は、後で作成されたシークレットを含む、その中のシークレットに適用されます。

プリンシパルに許可するには

付与

ノートブック、ジョブ、または REST API 呼び出しで値を読み取ります

READ SECRET

値を確認せずに特定のシークレットを検出する

REFERENCE SECRET カタログ全体で BROWSE が広すぎる場合は、シークレットまたはスキーマで指定します。これは読み取りアクセスを提供したり、プリンシパルが値を使用できるようにしたりするものではありません。

値を更新

WRITE SECRETこの権限のみを付与しても、シークレットへの読み取りアクセス権は付与されません。

スキーマにシークレットを作成する

CREATE SECRET スキーマまたはカタログ上の

シークレットに対する権限を他のユーザーに付与する

シークレット、スキーマ、またはカタログの所有権、またはMANAGE

プリンシパルに許可するには

付与

ノートブック、ジョブ、または REST API 呼び出しで値を読み取ります

READ SECRET

値を確認せずに特定のシークレットを検出する

REFERENCE SECRET カタログ全体で BROWSE が広すぎる場合は、シークレットまたはスキーマで指定します。これは読み取りアクセスを提供したり、プリンシパルが値を使用できるようにしたりするものではありません。

値を更新

WRITE SECRETこの権限のみを付与しても、シークレットへの読み取りアクセス権は付与されません。

スキーマにシークレットを作成する

CREATE SECRET スキーマまたはカタログ上の

シークレットに対する権限を他のユーザーに付与する

シークレット、スキーマ、またはカタログの所有権、またはMANAGE

特権を付与するには、カタログエクスプローラーを使用します。シークレットまたはスキーマを開き、「 パーミッション」(Permissions ) tabをクリックして、「 付与」(Grant ) をクリックします。SQL で付与するには、次のコマンドを実行します:

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 が必要です。

Databricksはdbutilsを使用することを推奨します。これはセル出力とLogs内の値を編集するためです。次の例では、データベースのユーザー名とパスワードを読み取ってJDBC読み取りを構成します。

Python
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)をご覧ください。

シークレットの一覧表示、更新、削除​

値を更新するには、シークレットに対するWRITE SECRETが必要です。コメントや有効期限を変更したり、削除したりするには、シークレット、そのスキーマ、またはそのカタログに対する所有権またはMANAGEが必要です。

  1. カタログエクスプローラーでスキーマに移動し、 [概要] ペインの [シークレット] をクリックしてシークレットを一覧表示します。
  2. 変更するシークレットをクリックします。
  3. 右上隅で、ケバブメニュー(縦に3つ並んだドット)をクリックし、 Edit または Delete を選択します。
  4. 編集するには、新しい値または有効期限を入力し、 確認 をクリックします。削除するには、シークレットの完全な名前を入力し、 削除 をクリックします。

シークレットアクセスを監査する​

system.access.audit システムテーブルはシークレットイベントを記録します。読み取りはaction_name = 'getSecret'で表示されます。過去7日間のシークレットイベントをリストするには、次のコマンドを実行します。

SQL
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-catalog OAuth APIスコープが必要です。secretsスコープは、ワークスペースのSecret Scopeにのみ適用されます。
  • Initスクリプト :グローバルまたはクラスタースコープのinitスクリプトでUnity Catalogシークレットを使用することはできません。
  • リモート開発 :dbutils.secretsにはDatabricks Runtimeでバックアップされたノートブックまたはジョブが必要なため、Databricks Connectおよびコンパイル済みJARランモードはUnity Catalogシークレットを読み取れません。

その他のリソース​

    • シークレット管理
    • Unity CatalogのシークレットとワークスペースのSecret Scopeを比較し、それぞれを使用できる場所をご確認ください。