はじめに

Databricks のサービスプリンシパルのシークレット値や PAT をハードコーディングせずに管理する方法を検討する中で、
Databricks が提供する Secrets 機能が手軽かつ実用的であることが分かりました。

本記事では、Databricks Secrets の概要と、利用が効果的なケースについて整理します。

Databricks Secrets の全体像

Databricks Secrets は、ノートブックやジョブから機密情報を安全に参照するための仕組みです。
次の2要素で構成されます。

Secret Scope
- 機密情報（Secret）を管理するコレクション
- Databricksが管理する暗号化されたデータベースに格納
- ユーザ・グループ等への権限付与の最小単位
Secret
- 機密情報の実体
- Secret Scope に {key: value} 形式のレコードとして登録

Secrets の主な特徴は以下の通りです。

シークレット値のノートブック出力は自動的にマスクされる（※制限あり）
シークレット値の参照・更新が可能なユーザをグループ単位で管理可能

ノートブックでの使用例

Databricks Secrets をノートブックで扱いやすい Databricks SDK for Python を用いた使用例を示します。
本項では以下の流れを説明します。

Secret Scope の作成
Secret の登録
Secret の参照・使用
Secret Scope に対する権限付与

Secret Scope の作成や権限付与には、
Databricks ワークスペース内のリソース（ジョブ、クラスター、Secrets など）を REST API 経由で操作するためのWorkspaceClientを利用します。

from databricks.sdk import WorkspaceClient
w = WorkspaceClient(
    host="https://<Databricks Workspaceのデプロイメント名>.cloud.databricks.com",
    client_id="サービスプリンシパルのクライアントID",
    client_secret"サービスプリンシパルのOauthシークレット"
)

1.Secret Scope作成

Secret Scopeの作成方法は以下の通りです。

w.secrets.create_scope(scope="<Secret Scopeを示す文字列>")

命名時の注意点は以下です。

ワークスペース内で一意である必要あり
使用可能文字：英数字、ダッシュ、アンダースコア、@、ピリオド
128 文字以内
大文字・小文字は区別されない

2.Secret登録

作成した Secret Scope に Secret を登録します。

w.secrets.put_secret(
    scope="<Secret Scopeを示す文字列>",
    key="<Secretのキー名を示す文字列>",
    string_value="<シークレット値を示す文字列>" 
)

Secretの命名についての注意点は以下です。

Secret Scope内で一意である必要あり
※同一名称にて登録した場合上書き扱いとなる
大文字と小文字は区別されない

3.Secretの参照・使用

登録した Secret を参照する方法は以下の通りです。

secret_value = dbutils.get_secret(
  scope="<Secret Scopeを示す文字列>",
  key="<Secretのキー名>"
)

ノートブック実行ユーザの権限で Secret を取得する場合は dbutils を利用可能です。

secret_value = dbutils.secrets.get(
  scope="<Secret Scopeを示す文字列>",
  key="シークレット値を示す文字列>"
)

print文などによるシークレット値の表示は、以下の通り制御されます。

Secret の利用例として、Databricks にホストされた生成 AI モデルに対して
PAT を用いて認証するケースを示します。

from openai import OpenAI
dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().get()
client = OpenAI(
    api_key=dbutils.secrets.get(
        scope="<Secret Scopeを示す文字列>",
        key="<Secretのキー名>"
    )
    base_url="<DatabricksにてホストされるLLMモデルのエンドポイントURL>"
)

response = client.chat.completions.create(
    model="databricks-gpt-5",
    messages=[
        {
            "role": "user",
            "content": "LLMModelへのユーザメッセージ"
        }
    ],
    max_tokens=5000
)

print(response.choices[0].message.content)

4.Secret Scopeに対する権限付与

Secret の共有単位は Secret Scope です。
permission に指定する値に応じて、以下の権限が付与されます。

READ: シークレットの読み取り
WRITE: シークレットの読み取り・書き込み
MANAGE: シークレットの読み取り・書き込み・権限管理

from databricks.sdk.service import workspace
w.secrets.put_acl(
    scope="<Secret Scopeを示す文字列>",
    principal="<権限付与対象のプリンシパル（ユーザ・グループ等）を示す文字列>",
    permission=workspace.AclPermission."<権限>"
)

Secretsの利用が検討できる代表的なケース

Secrets を活用しやすいケースは、
Databricks ワークスペース内でキーの発行・共有・認証が完結する場合です。

特に以下は Secrets の管理メリットが発揮しやすい対象です。

サービスプリンシパルのシークレット値
PAT トークン
外部 API の認証キー

ノートブック内での発行・共有が可能であり、
その過程でシークレット値が実行結果として出力されることを防げる点が大きな利点です。

運用時の制約

シークレット値のファイル書き出し制御不可

Secretsは print文等の表示制御は行われますが、ファイル書き出しは制御されません。
ユーザが参照権限を持つ Secret を平文でファイル出力することは可能であり、
これは Secrets の機能・権限設定では防止できません。

そのため、チーム利用時は運用ルールでのカバーが必要です。

平文でのシークレット値出力が必須となるケース

接続先システムの認証設定がノートブック内で完結しない場合、
シークレット値を平文で扱う必要が生じます。

例：

Power BI にサービスプリンシパルを設定する場合
→ GUI 上でクライアント ID とシークレット値を入力する必要あり

このようなケースでは、
Azure Key Vault や AWS Secrets Manager などのキー管理ツールを検討すべきです。

一方で、Databricks内で発行されるシークレットのハードコーディングをクイックに防ぎたいという観点では、
Databricks Secrets が最初の選択肢となり得ます。

まとめ

Databricks Secrets は、ノートブックやジョブにおける
シークレット値のハードコーディングを防ぐための、最も手軽な仕組みです。

シークレット値はノートブック上に表示されず、実行結果にも残らない
Secret Scope 単位で権限管理ができ、チーム利用にも向いている
Databricks ワークスペース内で完結する用途では導入コストが低い

一方で、

ファイル書き出しは制御できない
外部システムの GUI 設定が必須なケースでは平文扱いが避けられない

といった制約も存在します。

そのため、
「Databricks 内で発行・利用されるシークレットを安全に扱いたい」
という目的に対して、Databricks Secrets は 最初に検討可能な選択肢と言えます。

参考

https://docs.databricks.com/aws/ja/security/secrets/
https://databricks-sdk-py.readthedocs.io/en/latest/workspace/workspace/secrets.html