在 Unity 目錄中設定外部秘密

本頁說明如何將 Unity Catalog 架構連接到外部秘密管理器，使其秘密值保留在 Azure Key Vault 中。

關於外部秘密的運作方式及其限制，請參見 Unity 目錄中的外部秘密。

開始之前

• 符合 Unity Catalog 密碼的要求。
• 您的工作區必須啟用外部密鑰 Beta 版。
• 你想要外部備份的結構描述不得包含任何由 Azure Databricks 管理的秘密。 切換後端前先刪除現有的秘密。
• 你必須具備 Unity Catalog 與外部祕密管理工具之間的連線，以及供該連線用於驗證的 Unity Catalog 服務憑證。 若要建立這些項目，您必須在現有連線上具備 CREATE CONNECTION，或在中繼存放區上具備 CREATE CREDENTIAL 以建立連線，並且具有服務認證的存取權，或在中繼存放區上具備 USE CONNECTION 以建立服務認證。

• Azure Key Vault 支援僅適用於 Azure 上的 Azure Databricks，並使用 AZURE_KEY_VAULT 連線。

設定外部機密

建立服務憑證

連線會使用 Unity Catalog 服務認證，向您的外部祕密管理器進行驗證。

建立以受控識別或服務主體為後盾的服務認證，並授與其列出及讀取目標 金鑰保存庫 中祕密的權限。 例如，指派 金鑰保存庫 Secrets 使用者角色，或設定一個包含取得與列出秘密權限的等效存取政策。 相關說明請參見 建立服務憑證。

建立連結

建立一個 Unity 目錄連線，引用前一步的服務憑證，並指向你的外部秘密管理器。

目錄檢視器

1. 在 Azure Databricks 中，開啟目錄總管，點選+選單，選擇建立連線。
2. 輸入一個連線名稱，並選擇 Azure Key Vault 連線類型。
3. 選擇要用來驗證身分的服務憑證，並設定您的 金鑰保存庫 的 保存庫名稱。
4. 點擊 建立。

Databricks 命令行介面

將連接體 傳遞 ， --json使用 AZURE_KEY_VAULT 連接類型。 設定vault_name為你的 金鑰保存庫 名稱及credential服務憑證名稱：

databricks connections create --json '{
  "name": "my_key_vault_connection",
  "connection_type": "AZURE_KEY_VAULT",
  "options": {
    "vault_name": "my-vault",
    "credential": "my_key_vault_credential"
  }
}'

REST API

使用 /api/2.1/unity-catalog/connections 端點搭配 AZURE_KEY_VAULT 連線類型。 Azure Databricks 會將 vault_name 解析為 https://<vault_name>.vault.azure.net:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my_key_vault_connection",
    "connection_type": "AZURE_KEY_VAULT",
    "options": {
      "vault_name": "my-vault",
      "credential": "my_key_vault_credential"
    }
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/connections"

回傳一個帶有連結的結構

在目錄總管中設定該結構的秘密後端。

1. 在 Azure Databricks 中，開啟 Catalog Explorer，然後前往結構描述。

2. 在結構細節中，找到外部秘密管理器設定並點 選啟用。

   該架構不得包含任何 Azure Databricks 管理的秘密。 如果有的話，請先將其移除。 啟用 會維持停用狀態，直到結構描述中不含任何機密資料。

3. 選擇你在前一步建立的連線，然後確認。

這個結構現在由你的外部秘密管理器支援，而它的秘密資料會出現在 Unity 目錄中。

若要將結構指向不同的連線，請使用 Edit。 要將結構還原到 Azure Databricks 管理的儲存，請編輯結構並停用外部秘密。

設定或變更綱要的祕密後端，需要在父目錄上具備 USE CATALOG 權限、擁有該綱要的所有權或對其具備 MANAGE 權限，以及對連線具備 USE CONNECTION 權限。

讀取外部祕密

當結構外部備份後，它的秘密會出現在 Unity 目錄中，你就像閱讀其他 Unity 目錄的秘密一樣。 列出一個結構會觸發匯入，因此新加入的秘密只會在下一個清單之後出現。 兩片雲的讀取指令都是一樣的。

Dbutils

dbutils 會遮蔽機密資訊，且是讀取值的建議方式。 需要 Databricks Runtime 17.3 LTS 或以上，或無伺服器環境版本 4 或以上。

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

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

REST API

設定 include_value=true 並讀取 effective_value 欄位以回傳該值。 REST API 不會遮蔽回傳的值，但仍會稽核存取;Azure Databricks 建議dbutils改用。

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

你也可以在目錄總管中瀏覽並列出外部秘密，就像 Azure Databricks 管理的秘密一樣。 請參見 閱讀一個秘密。

如果 Unity 目錄中還沒出現秘密，你仍然可以透過名稱讀取它。 請提供外部秘密管理器中顯示的名稱，並套用 命名限制 中的字元替換規則。

其他資源