Unity Catalogシークレットを試す

Posted at 2026-07-18

はじめに

パスワード、トークン、APIキーなどの機密情報をコードに直接記述するのは避けるべきプラクティスであり、Databricksではこれまでシークレット管理の仕組みとしてワークスペースレベルのシークレット(シークレットスコープ)を提供してきました。

今回、Unity Catalogのセキュリティ保護可能なオブジェクトとしてシークレットを管理できるUnity Catalogシークレットがパブリックプレビューとなりました。

Unity Catalogのシークレット | Databricks on AWS

Unity Catalogシークレットは、パスワード、トークン、またはAPIキーなどの機密情報を格納するセキュリティ保護可能なオブジェクトです。ノートブックとジョブは、コードで値を公開することなくシークレットを参照できます。

本記事では、従来のシークレットとの違いを整理した上で、カタログエクスプローラのUIでのシークレット作成、権限付与、ノートブックからの取得を実際に試していきます。

従来のシークレット(シークレットスコープ)との違い

これまでのDatabricksシークレットは、ワークスペースレベルのシークレットスコープに整理される仕組みでした。Unity Catalogシークレットは、Unity Catalogの権限でシークレットを管理し、3レベルの名前空間で参照したい場合に使用します。主な違いを整理すると以下の通りです。

観点	従来のシークレット(シークレットスコープ)	Unity Catalogシークレット
スコープ	ワークスペースレベル	メタストアレベル(メタストアにアタッチされている全ワークスペースで利用可能)
名前空間	`scope/key`の2階層	`catalog.schema.secret`の3階層
アクセス制御	シークレットACL(MANAGE/WRITE/READ)	Unity Catalog権限(`READ SECRET`、`WRITE SECRET`、`REFERENCE SECRET`など)。カタログ/スキーマからの権限継承をサポート
UIでの管理	不可(CLI/API中心)	カタログエクスプローラで作成・更新・削除・権限管理が可能
監査	監査ログ	`system.access.audit`システムテーブルで他のデータ資産と同様に監査可能
有効期限	なし	有効期限を設定可能(期限切れ時はカタログエクスプローラに警告表示)
取得方法	`dbutils.secrets.get(scope, key)`	`dbutils.secrets.get(catalog, schema, key)`またはUnity Catalog REST API

ポイントは、シークレットがテーブルやボリュームと同じUnity Catalogのセキュリティ保護可能なオブジェクトになったことで、他のデータ資産に使用しているのと同じアクセスモデルと監査をシークレットに適用できるようになったことです。

権限モデル

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

権限	説明
`CREATE SECRET`	スキーマ内にシークレットを作成できるようにします。カタログまたはスキーマレベルで付与
`READ SECRET`	シークレット値を取得できるようにします
`WRITE SECRET`	シークレット値を更新できるようにします
`REFERENCE SECRET`	値へのアクセスなしで、Unity Catalog接続などからシークレットを名前で参照できるようにします

READ SECRETとREFERENCE SECRETの違いは「シークレットの値そのものにアクセスできるかどうか」です。READ SECRETはdbutilsやREST APIで生の値を取得できるのに対し、REFERENCE SECRETは値を一切見ることなく、Unity Catalog接続などのオブジェクトからシークレットを名前で紐付けることだけができます。接続の設定担当者にはREFERENCE SECRETのみを付与することで、シークレット値を秘匿したまま最小権限で運用できます。

事前準備

Unity Catalogシークレットを使うには以下が必要です。

ワークスペースがUnity Catalogに対して有効化されていること
Unity Catalog対応のコンピュートからアクセスすること
- Serverlessジョブ/ノートブック: 環境バージョン4以降
- クラシックコンピュート: 標準アクセスモードのDatabricks Runtime 17.3 LTS以降
dbutilsでシークレットを取得する場合も同様に、Databricks Runtime 17.3 LTS以降またはServerless環境バージョン4以降

また、スキーマにシークレットを作成するには、USE CATALOG権限を持ち、スキーマを所有しているか、スキーマに対するCREATE SECRETとUSE SCHEMAを持っている必要があります。

UIでのシークレット作成

カタログエクスプローラからシークレットを作成します。今回はtakaakiyayoi_catalog.secretsスキーマ配下に作成します。

スキーマの画面に移動し、右上の作成をクリックすると、作成できるオブジェクトの一覧にシークレットが追加されていることがわかります。テーブルやボリュームと並んでシークレットが表示されるのは新鮮です。なお、スキーマのオブジェクトフィルターにもシークレットタブが追加されています。

作成 > シークレットをクリックすると、作成ダイアログが表示されます。

以下を入力します。シークレット値は入力時からマスクされます。

シークレットの名前: sample_secret
シークレット値: 任意の値
カタログとスキーマ: takaakiyayoi_catalog / secrets
有効期限(オプション): 2026/08/31 00:00
コメント(オプション): これはサンプルシークレットです。

作成をクリックすると、シークレットのページに遷移します。作成者、作成日、更新者、有効期限などのメタデータが確認できます。テーブルなどと同様にタグも付与できます。

シークレットの有効期限が切れると、カタログエクスプローラに警告が表示されます。シークレットのローテーションを運用に組み込みやすい仕組みです。

権限の付与

シークレットの権限タブから付与をクリックすると、権限付与ダイアログが表示されます。

個々のシークレットレベルでは以下の権限を付与できます。

APPLY TAG: オブジェクトにタグを適用
READ SECRET: シークレット値の読み込み
REFERENCE SECRET: シークレットの参照(値へのアクセスなし)
WRITE SECRET: シークレット値の書き込みと更新
ALL PRIVILEGES: すべての権限
MANAGE: 権限の管理、削除、名前の変更など、所有権のような機能

SQLでも同様に付与できます。

GRANT READ SECRET ON SECRET takaakiyayoi_catalog.secrets.sample_secret TO `user@example.com`;

なお、カタログのBROWSE権限はUnity Catalogシークレットには適用されません。シークレットを検出可能にするには、個別のシークレットまたはそのスキーマに対してREAD SECRETまたはREFERENCE SECRETを付与する必要があります。

ノートブックからのシークレットの取得

dbutils.secrets.getにカタログ、スキーマ、キーを指定してシークレット値を取得します。従来のscope/key指定に加えて、catalog/schema/keyのシグネチャが追加されています。

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="takaakiyayoi_catalog", schema="secrets", key="sample_secret")

取得した値を表示しようとすると、伏字処理(redaction)が適用されて[REDACTED]と表示されます。ノートブックの出力やログでの偶発的な露出を防ぐ仕組みです。

my_secret

'[REDACTED]'

Databricksはシークレットの伏字処理が適用されるため、シークレットの読み込みにはdbutilsを推奨しています。

REST APIでの取得

Unity Catalog REST APIでも取得できます。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/takaakiyayoi_catalog.secrets.sample_secret"

注意点として、REST APIで取得されたシークレット値は伏字処理の対象外です。アクセスは引き続き監査ログに記録されますが、基本的にはdbutilsの利用が推奨されます。

監査

system.access.auditシステムテーブルにUnity Catalogシークレット関連のイベントが記録されます。例えば、特定の日付における特定ユーザーのシークレットイベントは以下のクエリーで確認できます。

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

シークレットへのアクセスをテーブルなどと同じシステムテーブルで横断的に監査できるのは、Unity Catalogに統合されたメリットと言えます。

制限事項

パブリックプレビュー時点での主な制限事項です。

SQLウェアハウス非対応: Unity Catalog対応コンピュート上のDatabricks Runtime 17.3 LTS以降またはServerlessが必要
グローバル検索に非表示: グローバル検索には表示されません
BROWSE権限非対応: 検出にはREAD SECRETまたはREFERENCE SECRETの付与が必要
initスクリプト非対応: グローバル/クラスターinitスクリプトでは使用不可
情報スキーマ未対応: 検出にはカタログエクスプローラまたはREST APIを使用
dbutilsのランタイムスコープ: リモート開発やコンパイル済みJARランモードなど、Databricks Runtime以外のコンテキストは非対応
OAuth APIスコープ: Unity CatalogシークレットAPIはunity-catalog OAuth APIスコープでのみアクセス可能
クォータ: スキーマごとに最大100個、メタストアごとに1,000個

まとめ

Unity Catalogシークレットによって、シークレットもテーブルやボリュームと同じガバナンスモデルに統合されました。個人的には以下の点が嬉しいポイントです。

UIで作成から権限管理まで完結する(従来はCLI/API中心でした)
カタログ/スキーマからの権限継承とREFERENCE SECRETによる最小権限の運用
有効期限によるローテーション運用のサポート
システムテーブルでの横断的な監査

従来のワークスペースレベルのシークレットも引き続き利用できますが、Unity Catalogのガバナンスに寄せていく流れの中で、新規のシークレットはUnity Catalogシークレットで管理していくのが良さそうです。ぜひお試しください。