メインコンテンツまでスキップ
に最終更新

Unity Catalogのシークレット

このページでは、Unity Catalogでシークレットを作成、読み取り、管理、およびガバナンスする方法について説明します。Unity Catalogシークレットは、パスワード、トークン、またはAPIキーなどの機密情報を格納するセキュリティ保護可能なオブジェクトです。ノートブックとジョブは、コードで値を公開することなくシークレットを参照できます。

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

注記

Unity Catalog シークレットは、Secret Scope に整理されるワークスペース レベルのDatabricks シークレットとは異なります。Unity Catalog シークレットは、Unity Catalog の権限でシークレットを管理し、3レベルの名前空間で参照したい場合に使用します。

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

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

Unity Catalog シークレットは、以下の方法で使用できます。

  • コードで値を取得します。 READ SECRET アクセスを使用すると、ユーザーは dbutils または Unity Catalog REST API を使用して、ノートブックとジョブからシークレット値を取得できます。その後、それを使用して外部システムとの認証を行うか、データを暗号化および復号化できます。
  • セッションスコープの Python または Scala UDF でその値を使用します。 セッションスコープの UDF を参照してください。
  • Unity Catalog Python UDF の値を使用します。 スカラー UDF またはバッチ UDF は、SECRETS 句で各シークレットを宣言します。Python UDF を参照してください。
  • Unity Catalog Scala UDF の値を使用します。 スカラー UDF は、SECRETS 句で各シークレットを宣言します。Scala UDF を参照してください。

UDF タイプ全体での要件とアクセス許可の動作については、UDF の要件とアクセス許可を参照してください。

UDF では、Databricks 管理のシークレット、または外部シークレットマネージャーによってサポートされるシークレットを使用できます。「Unity Catalog における外部シークレット」を参照してください。

UDF の要件とアクセス許可​

要件とアクセス許可の動作は、セッションスコープの UDF と Unity Catalog の UDF で異なります。

セッションスコープの UDF​

セッションスコープの Python UDF は databricks.secrets.get() でシークレットを取得し、セッションスコープの Scala UDF は com.databricks.Secrets.get() でシークレットを取得します。シークレットへのアクセスには、呼び出し元のアクセス許可が使用されます。

シークレットアクセスのためのコンピュート要件は、UDF の言語によって異なります。

  • Serverlessコンピュートでは、Python および Scala UDF に環境バージョン 6 以降のノートブックまたはジョブセッションを使用する必要があります。
  • クラシック コンピュートでは、セッションスコープの Python UDF には、標準アクセス モードまたは専用アクセス モードの Databricks Runtime 19 以降が必要です。
  • クラシック コンピュートでは、セッションスコープの Scala UDF には、標準アクセス モードの Databricks Runtime 19 以降が必要です。

Unity Catalog UDF​

スカラーおよびバッチ Unity Catalog Python UDF とスカラー Unity Catalog Scala UDF は、SECRETS 句でシークレットを宣言し、environment_version を 6 以上に明示的に設定する必要があります。これらは、Serverless Compute、Serverless SQL Warehouse、および標準アクセスモードで Databricks Runtime 19 以降を実行するクラシック コンピュートをサポートしています。

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

シークレットを宣言する UDF を作成または置換するには、ステートメントを実行するプリンシパルが、シークレットに対する READ SECRET と、その親カタログおよびスキーマに対する USE CATALOG および USE SCHEMA を持っている必要があります。ランタイム時に、UDF は現在の関数所有者の権限を使用します。呼び出し元には EXECUTE を含む通常の関数権限が必要ですが、宣言されたシークレットへの直接アクセスは必要ありません。関数の所有者が宣言されたシークレットを読み取る権限を失うと、UDF は失敗します。

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

SECRETS 句を使用する Unity Catalog の Python または Scala UDF は、専用アクセス モードのコンピュートで直接呼び出すことはできません。ただし、シークレットが有効な UDF を呼び出す Unity Catalog SQL 関数を作成し、その SQL 関数を属性ベース アクセス制御 (ABAC) の列マスクとして使用することができます。専用コンピュートでクエリーが実行されると、Databricks は列マスクの適用をServerless コンピュートに委任します。この例外は列マスクの適用中にのみ適用され、専用コンピュートでシークレットが有効な UDF の直接の呼び出しを有効にするものではありません。「サポートされていないコンピュート バージョン」を参照してください。

警告

シークレット値は UDF の実装内でのみ使用してください。シークレット値を返したり、UDF の結果に含めたりしないでください。シークレットのマスキングは、エラーや Logs における誤った露出を減らすのに役立ちますが、UDF のコードがクエリー結果でシークレットマテリアルを露出させるのを防ぐものではありません。

DatabricksはUnity Catalogシークレット値を暗号化して保存し、出力やLogsでの偶発的な露出を減らすためにシークレットの伏字処理を適用します。シークレットをローテーションするには、UIまたはUnity Catalog REST APIを使用してその値を定期的に更新します。

Unity Catalog シークレットの権限​

次の権限はシークレットを管理します。カタログ、スキーマ、または個々のシークレットレベルで付与でき、Unity Catalog の権限継承に従います。

権限

説明

CREATE SECRET

ユーザーがスキーマ内にシークレットを作成できるようにします。カタログまたはスキーマレベルで付与されます。

READ SECRET

ユーザーがシークレット値を取得できるようにします。

WRITE SECRET

ユーザーがシークレット値を更新できるようにします。

REFERENCE SECRET

値にアクセスすることなく、ユーザーがシークレットを参照できるようにします。

権限

説明

CREATE SECRET

ユーザーがスキーマ内にシークレットを作成できるようにします。カタログまたはスキーマレベルで付与されます。

READ SECRET

ユーザーがシークレット値を取得できるようにします。

WRITE SECRET

ユーザーがシークレット値を更新できるようにします。

REFERENCE SECRET

値にアクセスすることなく、ユーザーがシークレットを参照できるようにします。

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

始める前に​

Unity Catalog シークレットを使用するには、次の要件を満たす必要があります：

  • ワークスペースは Unity Catalog に対して有効になっている必要があります。概要については、Unity Catalog とはを参照してください。

  • シークレットには、Unity Catalog対応のコンピュートからアクセスする必要があります。Databricksでは、次のいずれかを推奨しています。

  • dbutilsでシークレットを取得するには、コンピュートはDatabricks Runtime 17.3 LTS以降、またはServerless環境バージョン4以降を実行する必要があります。

シークレットを作成します​

シークレットを作成するには、USE CATALOG権限を持ち、スキーマの所有者であるか、スキーマに対するCREATE SECRET権限とUSE SCHEMA権限を持っている必要があります。Unity Catalog シークレットの権限を参照してください。

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

シークレットの読み込み​

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

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

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

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

コードでシークレットを使用する​

dbutils.secrets.get で Unity Catalog のシークレットを読み取った後、返された値をアプリケーションコードに渡します。dbutils はセル出力と Logs 内の値を非表示にするため、値を公開せずに使用できます。

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

Python
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 サービス資格情報を使用して外部クラウド サービスに接続するを参照してください。

Python
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 Catalog での権限の管理を参照してください。

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

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

  2. 「 アクセス許可 」タブをクリックします。

  3. 付与 をクリックします。

  4. アクセスを許可するプリンシパルを選択し、 シークレットを作成 します。

    プリンシパルがUSE SCHEMAを持っていない場合、警告が表示され、それを付与するよう求められます。スキーマにシークレットを作成するには、USE SCHEMAも必要です。

  5. 確認 をクリックします。

シークレットへのアクセス権を付与します​

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

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

シークレットを一覧表示​

  1. カタログ エクスプローラーで、スキーマに移動します。
  2. 「**概要**」ペインで、「**シークレット**」をクリックすると、スキーマ内のすべてのシークレットが表示されます。

シークレットを更新​

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

  1. カタログエクスプローラーでスキーマに移動し、 概要 ペインで 「シークレット」 をクリックします。
  2. 更新するシークレットをクリックします。
  3. 右上隅で、ケバブメニュー（縦の点）をクリックし、 編集 を選択します。
  4. 新しい値または有効期限を入力し、 確認 をクリックします。

シークレットを削除する​

  1. カタログエクスプローラーでスキーマに移動し、 概要 ペインで 「シークレット」 をクリックします。
  2. 削除するシークレットをクリックします。
  3. 右上隅でケバブメニュー（縦の点）をクリックし、 削除 を選択します。
  4. シークレットの完全な名前を入力し、 削除 をクリックします。

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

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

SQL
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%";

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

顧客管理キーでシークレット値を暗号化する​

Databricksはdefaultで、Databricksが管理するキーでシークレット値を暗号化します。代わりに顧客管理キー（CMK）を使用できます。CMKで暗号化されたマネージドカタログ機能を有効にし、CMK構成をアカウントにアタッチすると、DatabricksはCMKを使用してシークレット値を暗号化します。詳細については、Unity Catalogの顧客管理キーを参照してください。

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

Databricks がシークレット値を保存する代わりに、外部シークレットマネージャーを使用してスキーマをバックアップできます。これにより、値はクラウドのシークレットマネージャーに保持されたまま、Unity Catalog で管理可能になります。AWS 上の AWS Secrets Manager および Azure 上の Azure Key Vault がサポートされています。外部シークレットの仕組みについては、「Unity Catalog における外部シークレット」を参照してください。外部シークレットマネージャーを使用してスキーマをバックアップする方法については、「Unity Catalog での外部シークレットの構成」を参照してください。

制限事項​

Unity Catalogのシークレットには次の制限があります。

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