Azure Databricks の運用現場では、ワークスペースに乱立するシークレットスコープと Azure Key Vault の対応関係をすばやく把握し、権限を安全に見直せることが重要です。本記事では、ノートブック・REST API・CLI を使って「スコープ一覧」と「紐付く Key Vault」を正確に棚卸しする具体手順と、Creator 限定の権限をワークスペース全体へ拡張する実務的な方法・ベストプラクティスをまとめます。
目次
対象読者・前提
- Azure Databricks ワークスペースの管理者、Platform/SRE、データエンジニア。
- シークレットスコープ（Databricks‑backed / Azure Key Vault‑backed）の基本を理解していること。
- Databricks CLI または REST API の利用経験があること（PAT/認証設定は済み）。
シークレットスコープの基礎整理（混在環境の要点）
同一ワークスペース内で Databricks‑backed と Azure Key Vault‑backed のスコープが混在しているケースはよくあります。棚卸しや監査を効率化するため、まず両者の見分け方・管理の要点を把握しましょう。
| 項目 | Databricks‑backed スコープ | Azure Key Vault‑backed スコープ |
|---|---|---|
| 格納場所 | Databricks の管理ストア | 外部の Azure Key Vault（AKV） |
| 一覧取得 | dbutils / REST / CLI で可 | スコープの一覧は可。 ただしシークレットのキー名一覧は取得制限がある（AKV 側が権限源泉） |
| 値参照 | dbutils.secrets.get で可（値はログ/出力に出さない） | dbutils.secrets.get で AKV から取得（AKV 側のアクセス許可が必須） |
| スコープ⇔Key Vault 紐付け | なし | スコープ作成時に固定（Vault URL / Resource ID がメタデータに残る） |
| ACL（READ/WRITE/MANAGE） | Databricks 側 ACL が有効 | Databricks 側 ACL + AKV 側アクセス制御の二段構え |
| 代表的な落とし穴 | Creator ロックの解除漏れ | AKV 側の RBAC/アクセスポリシー・ファイアウォールで実行時に失敗 |
ワークスペース内の「シークレットスコープ一覧」と「紐付く Key Vault」を確認する方法
概要（手段比較）
| 利用手段 | コマンド / API | 主な出力・利点 |
|---|---|---|
| Databricks ノートブック（dbutils） | dbutils.secrets.listScopes() | 既存スコープ名の一覧を即時取得。GUI 不要。 |
dbutils.secrets.list("SCOPE_NAME") | 指定スコープに格納されたキー名の一覧（Databricks‑backed で有効）。 キー名に Vault 名・URL など命名ルールを含めると後工程が楽。 | |
| Secrets REST API | GET /api/2.0/secrets/scopes/list | スクリプト・監査ジョブから JSON で自動取得。多くの環境で backend_type と Key Vault 情報（DNS 名 / Resource ID）を取得できるため、スコープ⇔Vault の対応表を作りやすい。 |
| Databricks CLI | databricks secrets list-scopes | スコープ名・バックエンド種別に加え、Key Vault の DNS 名（Vault 名入りの URL）/ Resource ID を確認可能。ワンライナーで棚卸しできる。 |
最速：ノートブックからスコープ名を一覧
GUI を開かず、ワークスペース内のスコープ名をすぐに確認できます。
# Python（Databricks ノートブック）
scopes = dbutils.secrets.listScopes()
for s in scopes:
print(s.name)
Databricks‑backed のスコープに限り、キー名の一覧も確認できます（値は表示されません）。
# Python（Databricks ノートブック）
for s in dbutils.secrets.list("SCOPE_NAME"):
print(s.key)
注意: Azure Key Vault‑backed スコープでは、セキュリティ上の理由からキー名の一覧が取得できない、もしくは空になる場合があります。Key Vault 紐付けの把握は次の REST / CLI を使うのが確実です。
確実：REST API で「スコープ⇔Key Vault」を JSON 取得
監査・自動化向けに最も柔軟です。PAT（個人アクセストークン）を環境変数に設定し、以下の例を実行します。
# 事前に環境変数を設定（例：Linux/macOS）
# export DATABRICKS_HOST="https://<your-workspace-host>"
# export DATABRICKS_TOKEN="<your-personal-access-token>"
# スコープ一覧を取得
curl -s -X GET \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
"${DATABRICKS_HOST}/api/2.0/secrets/scopes/list" \
| jq '.scopes[] | {name, backend_type, keyvault: (.keyvault_metadata // .backend_azure_keyvault)}'
よく使う整形例：
# scope, backend_type, key_vault_url（DNS 名）, resource_id を CSV で出力
curl -s -X GET \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
"${DATABRICKS_HOST}/api/2.0/secrets/scopes/list" \
| jq -r '
.scopes[]
| [
.name,
.backend_type,
(.keyvault_metadata.dns_name // .backend_azure_keyvault.dns_name // "N/A"),
(.keyvault_metadata.resource_id // .backend_azure_keyvault.resource_id // "N/A")
]
| @csv'
環境やバージョンによって Key Vault 情報のフィールド名（例：keyvault_metadata / backend_azure_keyvault）が異なることがあるため、上記のようにフォールバックで両方を参照しておくと堅牢です。
運用定番：Databricks CLI で一発棚卸し
CI/CD エージェントや運用端末に最適です。認証は databricks auth login（新 CLI）または databricks configure --profile（従来 CLI）で済ませておきます。
# JSON 出力にして JQ で整形
databricks secrets list-scopes --output JSON \
| jq -r '
.scopes[]
| [
.name,
.backend_type,
(.keyvault_metadata.dns_name // .backend_azure_keyvault.dns_name // "N/A"),
(.keyvault_metadata.resource_id // .backend_azure_keyvault.resource_id // "N/A")
]
| @tsv' \
| awk 'BEGIN{print "SCOPE\tBACKEND\tKEY_VAULT_DNS\tRESOURCE_ID"} {print}'
結果例：
SCOPE BACKEND KEY_VAULT_DNS RESOURCE_ID
kv-prod AZURE_KEYVAULT https://prod-kv.vault.azure.net/ /subscriptions/.../vaults/prod-kv
app-dbx DATABRICKS N/A N/A
スコープ一覧＋ACL も同時取得（棚卸しテンプレート）
監査観点では「誰が何にアクセスできるか」も同時に欲しいはずです。以下は CLI を使ったシンプルな棚卸しテンプレートです。
# スコープごとの ACL を列挙（READ/WRITE/MANAGE）
# 注意：API 呼び出し数が多くなるため、夜間バッチなどで実行推奨
echo -e "SCOPE\tBACKEND\tKEY_VAULT_DNS\tPRINCIPAL\tPERMISSION" > scopes_acls.tsv
databricks secrets list-scopes --output JSON
| jq -r '.scopes[] | @base64'
| while read -r row; do
_jq() { echo ${row} | base64 --decode | jq -r ${1}; }
scope=$(_jq '.name')
backend=$(_jq '.backend_type')
kvdns=$(_jq '.keyvault_metadata.dns_name // .backend_azure_keyvault.dns_name // "N/A"')
databricks secrets list-acls --scope "${scope}" --output JSON
| jq -r '.items[] | [.principal, .permission] | @tsv'
| while IFS=$'\t' read -r principal permission; do
echo -e "${scope}\t${backend}\t${kvdns}\t${principal}\t${permission}" >> scopes_acls.tsv
done
done 生成された scopes_acls.tsv を CMDB やデータカタログに取り込むと、権限監査が自動化できます。
スコープ作成時「作成者のみ」だった権限をワークスペース全体へ変更する
背景
スコープは作成直後、Creator（作成者）に権限が限定されることが多く、他ユーザーが参照できずジョブが失敗する原因になりがちです。安全に開放するには、必要最小権限の原則を守りつつ、対象グループまたは全ユーザー（All‑Users）への ACL を設定します。
Databricks CLI で一括変更
「ワークスペース全体に READ を許可」する最小例です（必要に応じて WRITE / MANAGE）。
# 全スコープに対して users（All‑Users）へ READ を付与
databricks secrets list-scopes --output JSON \
| jq -r '.scopes[].name' \
| while read -r scope; do
echo "Grant READ to users on ${scope}"
databricks secrets put-acl --scope "${scope}" --principal "users" --permission READ
done
ピンポイントで特定スコープのみ変更する場合：
databricks secrets put-acl --scope "SCOPE_NAME" --principal "users" --permission READ
# 変更の確認
databricks secrets list-acls --scope "SCOPE_NAME"
権限の意味（実務的な解釈）
| 権限 | できること | 注意点 |
|---|---|---|
| READ | ノートブック/ジョブで dbutils.secrets.get を使い値を取得 | ログ・エラー出力に値を露出させない（必ずマスク） |
| WRITE | Databricks‑backed スコープにシークレットを登録・更新 | AKV‑backed では AKV 側の更新が必要。WRITE を付けても Databricks からは登録できない |
| MANAGE | スコープの ACL 管理（付与/剥奪） | 誤付与で広範囲に影響。最小人数に限定 |
ワークスペース UI で変更
- Data → Security → Secret Scopes を開く。
- 対象スコープの Permissions を選択。
- Add principal から
users（全ユーザー）または特定グループを追加し、READ / WRITE / MANAGE を選択。 - 保存して反映。
ベストプラクティス：全ユーザーではなく、data-scientists や etl-jobs などの SCIM 連携グループへ付与する方が安全です。ジョブ専用には サービスプリンシパルを用意し、その ID へ必要最小権限で付与します。
実務で役立つスクリプト集
監査 CSV を作る Bash ワンライナー
# scopes_inventory.csv を作る
echo "scope,backend,key_vault_dns,resource_id,principal,permission" > scopes_inventory.csv
databricks secrets list-scopes --output JSON \
| jq -r '.scopes[] | @base64' \
| while read -r row; do
_jq() { echo ${row} | base64 --decode | jq -r ${1}; }
scope=$(_jq '.name')
backend=$(_jq '.backend_type')
kvdns=$(_jq '.keyvault_metadata.dns_name // .backend_azure_keyvault.dns_name // ""')
rsrc=$(_jq '.keyvault_metadata.resource_id // .backend_azure_keyvault.resource_id // ""')
databricks secrets list-acls --scope "${scope}" --output JSON
| jq -r --arg s "${scope}" --arg b "${backend}" --arg d "${kvdns}" --arg r "${rsrc}"
'.items[] | [$s,$b,$d,$r,.principal,.permission] | @csv'
done >> scopes_inventory.csv ノートブック（Python）で REST API を叩き DataFrame 化
ワークスペース内で軽く可視化したい時の例です（PAT はシークレットから参照する想定）。
# Python（Databricks ノートブック）
import os, json, requests
from pyspark.sql import SparkSession
host = os.environ.get("DATABRICKS_HOST") # 例： https://.azuredatabricks.net
token = dbutils.secrets.get("infra-secrets", "pat_token") # PAT は Databricks‑backed に格納して参照
headers = {"Authorization": f"Bearer {token}"}
resp = requests.get(f"{host}/api/2.0/secrets/scopes/list", headers=headers, timeout=30)
scopes = resp.json().get("scopes", [])
rows = []
for s in scopes:
name = s.get("name")
backend = s.get("backend_type")
kv = s.get("keyvault_metadata") or s.get("backend_azure_keyvault") or {}
rows.append((name, backend, kv.get("dns_name"), kv.get("resource_id")))
spark = SparkSession.builder.getOrCreate()
df = spark.createDataFrame(rows, ["scope", "backend", "key_vault_dns", "resource_id"])
display(df.orderBy("scope")) 安全運用のチェックリスト
- 命名規約：スコープ名・キー名に環境/用途（例：
kv-prod/payments-api-key）を含め、混在時の誤用を予防。 - Creator ロック解除：作成直後に必要なグループへ READ を付与。広げる前にジョブ影響を棚卸し。
- Key Vault 依存関係：AKV‑backed は Databricks 側の ACL だけでは動かない。AKV 側の RBAC/アクセスポリシー/ファイアウォールも点検。
- ログ衛生：シークレット値を
printやエラーログに出さない（マスク・プレースホルダで代替）。 - CMDB 連携：CLI/REST の JSON を定期収集し、差分検知・棚卸しを自動化。
- 変更履歴：ACL 変更は監査ログに残る。変更申請とチケット紐付けを徹底。
動作確認の基本シナリオ（失敗時の典型エラー）
| シナリオ | 確認手順 | よくあるエラー | 対処 |
|---|---|---|---|
| Databricks‑backed の参照 | dbutils.secrets.get("SCOPE","KEY") | SECRET_SCOPE_READ_PERMISSION_DENIED | スコープの READ を付与 |
| AKV‑backed の参照 | 同上 | AKV 側 403 / NotFound、タイムアウト | AKV の RBAC/アクセスポリシー、ファイアウォール、プライベートエンドポイントを確認 |
| CLI/REST で一覧 | list-scopes | 401/403（認証失敗） | PAT/ログイン・スコープ権限を再設定 |
よくある質問（FAQ）
Q. 既存スコープの Key Vault を後から変更できますか？
A. できません。スコープ作成時に固定です。Vault を変える場合は新スコープを作成し、参照先を切り替えてから旧スコープを廃止します。
Q. スコープの削除は安全ですか？
A. 参照ジョブが残っていると失敗や本番障害につながります。利用調査（検索・リポジトリ横断 grep・ダッシュボード依存関係）を行い、メンテナンス窓で実施してください。
Q. 値を丸見えにせずに接続検証したい
A. テスト接続は値を直接出さず、try/except で成功/失敗のみロギングする実装を推奨します（例：HTTP 200 が返れば成功）。
Q. どの権限から付けるべき？
A. 原則は READ のみ。WRITE/MANAGE は管理者または IaC パイプラインのテクニカルユーザーに限定します。
運用設計テンプレート（サンプル・ポリシー）
- 命名規則：
<env>-<system>-<purpose>（例：prod-bi-snowflake-creds） - ACL 標準：グループ
etl-jobsへ READ、platform-adminsへ MANAGE、サービスプリンシパルへ必要最小。 - AKV 方針：ファイアウォールは必要サブネットのみ許可。Managed Identity/Access Connector を優先。
- 監査：月次で
list-scopes+list-aclsを収集、差分レポートを配布。
まとめ（実務での使い分け）
- 即時確認：ノートブックの
dbutils.secrets.listScopes()。 - 正確な対応表：REST API または CLI で backend_type と Key Vault 情報を取得。
- 権限の是正：CLI で
put-aclを活用。広げすぎず、グループ単位で最小付与。 - 自動化：CSV/JSON を CMDB に取り込み、差分検知・棚卸しをジョブ化。
付録：コマンド早見表
| 目的 | コマンド / API | 備考 |
|---|---|---|
| スコープ名の一覧 | dbutils.secrets.listScopes() | ノートブック上で即時 |
| スコープ内キー名の一覧 | dbutils.secrets.list("SCOPE_NAME") | Databricks‑backed のみ有効 |
| スコープ一覧（JSON） | GET /api/2.0/secrets/scopes/list | backend_type と Key Vault 情報を取得可能 |
| CLI で一覧 | databricks secrets list-scopes --output JSON | JQ と併用で棚卸しが高速 |
| ACL の付与 | databricks secrets put-acl --scope SCOPE --principal users --permission READ | WRITE / MANAGE も指定可 |
| ACL の確認 | databricks secrets list-acls --scope SCOPE | 監査ログ取得の前段 |
付録：トラブル時の診断コマンド
# 認証状態（新 CLI）
databricks auth env
databricks auth profiles
# 単一スコープの詳細と ACL
databricks secrets list-scopes --output JSON | jq '.scopes[] | select(.name=="SCOPE_NAME")'
databricks secrets list-acls --scope "SCOPE_NAME" --output JSON
# Key Vault 到達性（VNET/Firewall/Private Endpoint の切り分けに）
# curl または tcpping 相当でネットワーク診断（企業プロキシ環境に注意）
結語
シークレットの混在運用は「現状可視化」「権限の標準化」「自動化」の三段で安定します。まずは CLI/REST でスコープ⇔Key Vault の対応表を作り、Creator ロックを正しく外してグループ単位の最小権限へ是正。最後に定期ジョブで差分監査を回すことで、セキュリティと開発速度の両立を図れます。
コメント