Unity カタログのシークレット

このページでは、Unity カタログでシークレットを作成、読み取り、管理、管理する方法について説明します。 Unity カタログ シークレットは、パスワード、トークン、API キーなどの機密性の高いマテリアルを格納するセキュリティ保護可能なオブジェクトです。 ノートブックとジョブからはコードの値を人目にさらすことなくシークレットを参照できます。

Unity カタログ シークレットは 3 レベルの名前空間 (catalog.schema.secret) を使用し、メタストアにアタッチされているワークスペース全体で使用できます。 それらには Unity カタログの権限が適用されます。 これにより、他のデータ資産に使用するのと同じアクセス モデルと監査をシークレットに適用できます。

Note

Unity カタログ シークレットは、シークレット スコープに編成されたワークスペース レベルのAzure Databricks シークレットとは異なります。 Unity カタログ特権でシークレットを管理し、3 レベルの名前空間で参照する場合は、Unity カタログ シークレットを使用します。

Unity Catalog シークレットの仕組み

Unity カタログ シークレットは、完全修飾名が catalog.schema.secretされたスキーマのセキュリティ保護可能なオブジェクトです。 他の Unity カタログのセキュリティ保護可能なオブジェクトと同様に、シークレットはカタログとスキーマからの特権の継承をサポートします。 セキュリティ保護可能なオブジェクトと継承の詳細については、 Unity カタログのセキュリティ保護可能なオブジェクトのリファレンスを参照してください。

Unity カタログ シークレットは、次の方法で使用できます。

• コード内の値を取得します。 READ SECRETアクセス権を持つユーザーは、dbutilsまたは Unity カタログ REST API を使用して、ノートブックとジョブからシークレット値を取得できます。 その後、外部システムで認証を行ったり、データの暗号化と暗号化解除を行ったりするために使用できます。
• その値はセッションスコープ付きのPythonやScala UDFで使う。 セッション スコープの UDFを参照してください。
• その値はUnity CatalogのPython UDFで使います。 スカラーまたはバッチUDFは、各シークレットを SECRETS 節で宣言します。 Python UDFを参照してください。
• その値はUnityカタログのScala UDFで使います。 スカラーUDFは、各秘密をその SECRETS 節で宣言します。 Scala UDFを参照してください。

UDFタイプ間の要件および権限動作については、「 UDF要件および権限」を参照してください。

UDFはAzure Databricksで管理される秘密や外部の秘密管理者によって裏付けられた秘密を使用できます。 Unity カタログの外部秘密を参照してください。

UDFの要件と許可

要件や権限の挙動は、セッションスコープ型UDFとUnity Catalog UDFで異なります。

セッション スコープの UDF

セッションスコープのPython UDFはdatabricks.secrets.get()で秘密を取得し、セッションスコープのScala UDFはcom.databricks.Secrets.get()で秘密を取得します。 シークレットアクセスは発信者の権限を利用します。

秘密アクセスの計算要件はUDF言語に依存します:

• サーバーレス計算では、ノートブックやジョブセッションはPythonやScala UDFで環境バージョン6以上を使用する必要があります。
• クラシックコンピュートでは、セッションスコープのPython UDFは、標準または専用アクセスモードでDatabricks Runtime 19以上が必要です。
• クラシックなコンピュートでは、セッションスコープのScala UDFはDatabricks Runtime 19以上と標準アクセスモードが必要です。

Unity カタログ UDF

スカラーおよびバッチの Unity Catalog Python UDF と、スカラー Unity Catalog Scala UDF は、SECRETS 句でシークレットを宣言し、environment_version を明示的に 6 以上に設定する必要があります。 サーバーレスコンピュート、サーバーレスSQLウェアハウス、そしてDatabricks Runtime 19以上を標準アクセスモードで動作させるクラシックコンピュートをサポートしています。

Pro SQL ウェアハウスは、シークレットを使うスカラーおよびバッチ Unity カタログ Python UDF をサポートしています。 Unity CatalogのScala UDFでシークレットを使用するものは、プロのSQLウェアハウスではサポートされていません。

秘密を宣言するUDFを作成または置き換えるためには、その文を実行するプリンシパルが秘密に READ SECRET 、親カタログおよびスキーマに USE CATALOG および USE SCHEMA を持たせていなければなりません。 実行時には、UDFは現在の関数所有者の権限を使用します。 呼び出し者は通常の関数権限( EXECUTEを含む)を必要としますが、宣言された秘密に直接アクセスする必要はありません。 関数の所有者が宣言された秘密の読み込み権限を失うと、UDFは失敗します。

専用コンピュートの列マスク内でシークレット対応のUDFを使用する

SECRETS条項を使うUnity Catalog PythonやScala UDFを専用アクセスモードの計算で直接呼び出しすることはできません。 しかし、Unity CatalogのSQL関数を作成してシークレットで有効なUDFを呼び出し、SQL関数を属性ベースのアクセス制御(ABAC)カラムマスクとして使うことは可能です。 クエリが専用コンピュートで実行される場合、Azure Databricksはカラムマスクの強制をサーバーレスコンピュートに委譲します。 この例外はカラムマスクを強制する場合にのみ適用されます。専用計算で秘密が有効化されたUDFの直接呼び出しは可能にしません。 「 サポートされていないコンピュートバージョン」を参照してください。

Warning

秘密値はUDF実装内でのみ使用してください。 秘密値を返したり、UDF結果に含めたりしないでください。 秘密の黒塗りはエラーやログでの偶発的な露出を減らすのに役立ちますが、UDFコードがクエリ結果に秘密資料を露出させるのを防ぐものではありません。

Azure Databricksは、暗号化された Unity カタログ シークレット値を格納し、シークレットの再処理を適用して、出力とログの偶発的な露出を減らします。 シークレットをローテーションするには、UI または Unity Catalog REST API でその値を定期的に更新します。

Unity Catalog シークレットの権限

次の特権によってシークレットが管理されます。 カタログ、スキーマ、または個々のシークレット レベルで付与できます。これらは Unity カタログの特権の継承に従います。

権限	Description
CREATE SECRET	ユーザーがスキーマにシークレットを作成できるようにします。 カタログ レベルまたはスキーマ レベルで付与されます。
READ SECRET	ユーザーがシークレット値を取得できるようにします。
WRITE SECRET	ユーザーがシークレット値を更新できるようにします。
REFERENCE SECRET	ユーザーが値にアクセスできなくても秘密を参照できるようにします。

スキーマにシークレットを作成するには、ユーザーが USE CATALOG 権限を持ち、スキーマを所有しているか、スキーマに CREATE SECRET して USE SCHEMA している必要があります。 権限を付与する方法については、「 Unity カタログでの権限の管理」を参照してください。

Requirements

Unity カタログ シークレットを使用するには、次の要件を満たす必要があります。

• ワークスペースが Unity Catalog に対して有効にされている必要があります。 概要については、「 Unity カタログとは」を参照してください。
• Unity カタログ対応コンピューティングからシークレットにアクセスする必要があります。 Azure Databricksでは、次のいずれかをお勧めします。
  • 環境バージョン 4 以降を使用するサーバーレス ジョブとノートブック。
  • Databricks Runtime 17.3 LTS 以降を実行する、標準アクセス モード のクラシック コンピュート。
• dbutilsを使用してシークレットを取得するには、コンピューティングで Databricks Runtime 17.3 LTS 以降、またはサーバーレス環境バージョン 4 以降を実行する必要があります。

シークレットを作成する

シークレットを作成するには、 USE CATALOG アクセス許可を持ち、スキーマを所有しているか、スキーマに対する CREATE SECRET と USE SCHEMA が必要です。 Unity カタログ シークレットの特権を参照してください。

カタログ エクスプローラー

1. Azure Databricks ワークスペースで、[カタログ] をクリックしてカタログ エクスプローラーを開きます。
2. シークレットを作成するスキーマに移動します。
3. [> シークレットの作成] をクリックします。
4. 名前と値を入力します。 必要に応じて、 コメント と有効期限を追加 します。 シークレットの有効期限が切れると、カタログ エクスプローラーに警告が表示されます。
5. Create をクリックしてください。

REST API

/api/2.1/unity-catalog/secrets エンドポイントを使用して、次の cURL コマンドを実行します。

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

シークレットを読み取る

シークレット値を読み取る場合は、シークレットまたは親カタログまたはスキーマに対する READ SECRET が必要です。

Secrets ユーティリティ (dbutils.secrets)

Azure Databricks では、シークレットのマスキングが適用されるため、シークレットを読み取るには dbutils を推奨しています。 このオプションには、Databricks Runtime 17.3 LTS 以降、またはサーバーレス環境バージョン 4 以降が必要です。

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

詳細については、「 シークレット ユーティリティ (dbutils.secrets)」を参照してください。

REST API

Warning

Unity カタログ REST API で取得されたシークレット値はシークレットの編集の対象になりませんが、アクセスは監査ログに記録されます。 Azure 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.default.example_secret"

コードに秘密を使わせてください

dbutils.secrets.getでUnityカタログのシークレットを読み取ったら、返された値をアプリケーションコードに渡します。 dbutils セル出力やログの値を黒塗りにするので、露出せずに使えます。

以下の例では、シークレットをベアラートークンとして用いて外部APIを呼び出します。

import requests

api_key = dbutils.secrets.get(catalog="main", schema="default", key="service_api_key")

response = requests.get(
    "https://api.example.com/v1/resource",
    headers={"Authorization": f"Bearer {api_key}"},
)
response.raise_for_status()

以下の例では、秘密値を取得し、それを dbutils.credentials.getServiceCredentialsProvider に渡してAWS SDK用のboto3セッションを設定するものです。 サービス認証名自体は機密性が低いため、この例では取得した秘密値を別のSDK呼び出しに連結させるために秘密名を秘密に保存しています。 サービス認証情報の詳細については、「 Unity Catalogのサービス認証情報を使って外部クラウドサービスに接続する」をご覧ください。

import boto3

credential_name = dbutils.secrets.get(catalog="main", schema="default", key="service_credential_name")

boto3_session = boto3.Session(
    botocore_session=dbutils.credentials.getServiceCredentialsProvider(credential_name),
    region_name="your-aws-region",
)
sm = boto3_session.client("secretsmanager")

シークレットに対するアクセス許可を管理する

シークレットを作成できるユーザーを制御するには、カタログレベルまたはスキーマ レベルで CREATE SECRET を付与します。 アクセスを制御するには、カタログ、スキーマ、または個々のシークレット レベルで READ SECRET、 WRITE SECRET、または REFERENCE SECRET を付与します。 特権の継承が適用されます。 権限の付与と取り消しの詳細については、 Unity カタログでの権限の管理に関するページを参照してください。

シークレットを作成する権限を付与する

カタログ エクスプローラー

1. カタログ エクスプローラーで、スキーマに移動します。

2. [Permissions] タブをクリックします。

3. [許可] をクリックします。

4. アクセス権を付与するプリンシパルを選択し、[ CREATE SECRET] を選択します。

   プリンシパルに USE SCHEMAがない場合は、それを許可するように求める警告メッセージが表示されます。 USE SCHEMA は、スキーマにシークレットを作成するためにも必要です。

5. [Confirm](確認) をクリックします。

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

REST API

/api/2.1/unity-catalog/permissions/schema/{schema_name} エンドポイントを使用して、次の cURL コマンドを実行します。

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

シークレットへのアクセスを許可する

カタログ エクスプローラー

1. カタログ エクスプローラーで、シークレットに移動してクリックします。
2. [Permissions] タブをクリックします。
3. [許可] をクリックします。
4. プリンシパルと付与する特権を選択し、[ 確認] をクリックします。

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

REST API

/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret} エンドポイントを使用して、次の cURL コマンドを実行します。

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

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

シークレットのリスト

カタログ エクスプローラー

1. カタログ エクスプローラーで、スキーマに移動します。
2. [ 概要 ] ウィンドウで、[ シークレット ] をクリックして、スキーマ内のすべてのシークレットを表示します。

Secrets ユーティリティ (dbutils.secrets)

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

REST API

page_sizeを使って1ページあたりの結果数をコントロールできます。 さらに多くの結果がある場合、回答には next_page_tokenが含まれます。

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  --data-urlencode "page_size=100" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

次のページを取得するには、前の応答の next_page_token 値を page_token パラメータとして渡します。

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  --data-urlencode "page_token=<next_page_token>" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

シークレットを更新する

シークレット値を更新するには、シークレットに WRITE SECRET が必要です。

カタログ エクスプローラー

1. カタログ エクスプローラーでスキーマに移動し、[概要] ウィンドウの [シークレット] をクリックします。
2. 更新するには、シークレットをクリックします。
3. 右上隅のケバブ メニュー (垂直ドット) をクリックし、[ 編集] を選択します。
4. 新しい値または有効期限を入力し、[ 確認] をクリックします。

REST API

更新要求には、 update_mask パラメーターが必要です。 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.default.example_secret?update_mask=*"

シークレットを削除します

カタログ エクスプローラー

1. カタログ エクスプローラーでスキーマに移動し、[概要] ウィンドウの [シークレット] をクリックします。
2. 削除するシークレットをクリックします。
3. 右上隅にあるケバブ メニュー (垂直ドット) をクリックし、[削除] を選択 します。
4. シークレットの完全な名前を入力し、[ 削除] をクリックします。

REST API

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Unity Catalog のシークレットの監査イベント

system.access.audit システム テーブルには、Unity カタログ シークレットに関連するイベントが記録されます。 たとえば、特定の日付のユーザーのすべてのシークレット イベントを表示するには、次のクエリを実行します。

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

監査ログの詳細については、「 監査ログ システム テーブルリファレンス」を参照してください。

カスタマー マネージド キーを使用してシークレット値を暗号化する

既定では、Azure Databricksは Databricks マネージド キーを使用してシークレット値を暗号化します。 代わりにカスタマー マネージド キー (CMK) を使用できます。 CMK で暗号化されたマネージド カタログ機能を有効にし、アカウントに CMK 構成をアタッチする場合、Azure Databricksは CMK を使用してシークレット値を暗号化します。 詳細については、「 Unity カタログのカスタマー マネージド キー」を参照してください。

外部シークレットマネージャーを使用してシークレットをバックアップする

Azure Databricksが秘密値を保存する代わりに、外部のシークレットマネージャでスキーマをバックアップして、値はクラウドのシークレットマネージャーに残しつつUnity Catalog内で管理できるようにできます。 AWS Secrets Manager on AWS と Azure Key Vault on Azure はサポートされています。 外部シークレットの仕組みについては、 Unity Catalogの外部シークレットを参照してください。 外部シークレットマネージャーでスキーマを裏付けるには、「 Unity Catalogの外部シークレットの設定」を参照してください。

Limitations

Unity カタログ シークレットには、次の制限があります。

• SQLウェアハウスからの直接アクセスは制限されています。 Unity Catalogの秘密はSQLウェアハウスから直接取得することはできません。 スカラーおよびバッチの Unity Catalog Python UDF は、Pro およびサーバーレス SQL ウェアハウス上で、それぞれの SECRETS 句で宣言されたシークレットにアクセスできます。 Scalar Unity Catalog Scala UDFはサーバーレスSQLウェアハウス上でのみ宣言された秘密にアクセスできます。
• 専用計算で直接 SECRETS UDF呼び出しはありません。 専用アクセス モードのコンピュートでは、SECRETS 句を使用するスカラーまたはバッチの Unity Catalog Python UDF、あるいはスカラーの Unity Catalog Scala UDF を直接呼び出すことはできません。 カラムマスク例外については、「 専用計算でカラムマスクでシークレット有効UDFを使用する」を参照してください。
• グローバル検出なし。 Unity カタログシークレットはグローバル検索には表示されません。
• BROWSE 権限はサポートされません。 BROWSE は Unity カタログ シークレットには適用されません。 シークレットを検出できるようにするには、個々のシークレットまたはそのスキーマに READ SECRET または REFERENCE SECRET を付与します。
• init スクリプトはありません。 Unity カタログ シークレットは、グローバル スクリプトまたはクラスター初期化スクリプトでは使用できません。 Azure Databricksでは、可能な限りスクリプトを初期化するのではなく、専用の機能を使用することをお勧めします。
• 情報スキーマがありません。 シークレット用の information schema テーブルはまだ利用できません。 カタログ エクスプローラーまたは REST API を使用して検出します。
• dbutils ランタイム スコープ。 dbutils 取得は、Databricks ランタイムベースのノートブックとジョブでサポートされています。 リモート開発やコンパイル済み JAR 実行モードなど、Databricks 以外のランタイム コンテキストはサポートされていません。
• OAuth API スコープ。 Unity カタログ シークレット API には、 unity-catalog OAuth API スコープでのみアクセスできます。 secrets API スコープは、ワークスペース レベルのAzure Databricks シークレットにのみ使用します。
• クォータ制限 スキーマあたり最大 100 個のシークレットと、メタストアあたり 1,000 個。