Unity Catalog 中的密鑰

Unity Catalog 密鑰是一個可保護的物件,用來儲存敏感的憑證,例如密碼、權杖或 API 金鑰。 Secrets 使用三層命名空間(catalog.schema.secret),且在連接於中繼存放區的每個工作區中皆可取得。

你用與其他資料資產相同的 Unity Catalog 權限來管理秘密值,甚至連個別秘密值都一樣。 使用者可以瀏覽 Secret 而無法讀取或使用,你可以用自己的金鑰加密 Secret 值,並透過稽核記錄記錄每一次讀取或變更。

Unity Catalog secrets 可以由 Azure Databricks 管理,或以 Azure Key Vault 為後端。 請參閱 Unity 目錄中的 Azure Key Vault secrets。

Requirements

建立密碼

秘密存在於結構描述中。 在一個只有需要的主體身分能存取的結構描述中建立祕密。 要決定如何將祕密分組成結構,請參見「依誰需要這些祕密來分組」。

結構描述會儲存 Azure Databricks 管理的祕密或 Azure Key Vault 所支援的祕密,而不是兩者,所以你在設定結構描述時可以選擇值的儲存位置。 關於 Azure Key Vault-backed schema,請參見「在 Azure Key Vault-backed 架構中建立祕密」。

建立由 Azure Databricks 管理的祕密

要建立由 Azure Databricks 管理的祕密,你需要在目錄上具有USE CATALOG,以及擁有該結構描述,或對該結構描述具有CREATE SECRET和USE SCHEMA。

要建立應用程式秘密的結構描述,請執行以下操作:

CREATE SCHEMA IF NOT EXISTS main.orders_app;

目錄檢視器

  1. 在你的 Azure Databricks 工作區中,點選目錄以開啟目錄總管。
  2. 前往您要建立密鑰的結構描述。
  3. 按一下 建立 > 密鑰。
  4. 輸入 一個名字 和 數值。 可選擇性地加上 註解 和 有效期限。 如果秘密過期,目錄瀏覽器會顯示警告。
  5. 點擊 建立。

REST API

要建立密鑰,請執行以下操作:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "orders_app",
    "name": "db_password",
    "value": "your_secret_value",
    "comment": "Password for the orders database"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

在以 Azure Key Vault 作為後盾的結構描述中建立密鑰

管理員用 Azure Key Vault 備份一次結構描述。 之後,你在 Azure Key Vault 中建立、更新並輪換其祕密,這些祕密就會顯示在 Unity Catalog 的結構描述中。 若要為結構描述提供支援,請參閱 Unity Catalog 中的 Azure Key Vault 秘密。

  1. 在 Azure Key Vault 中建立作為該結構描述後盾的祕密。
  2. 請依名稱閱讀這個祕密。 請參見 閱讀一個秘密。

授權存取機密

授予符合每個主體所需操作的特權。 除了 BROWSE 之外,每個主體身分也需要對父目錄和結構描述具有 USE CATALOG 和 USE SCHEMA。 在目錄或綱要上被賦予的權限適用於其中的秘密物件,包括後續建立的秘密物件。

讓主體能夠 獎助金
讀取筆記本、工作或 REST API 呼叫中的值 READ SECRET
在不看其值的情況下,發掘特定的密鑰 REFERENCE SECRET 在秘密或結構描述上,當 BROWSE 整個目錄過於寬泛時。 它不會給主體讀取權限,也不會讓主體使用該值。
更新該值 WRITE SECRET。 僅授予此權限並不代表能讀取祕密。
在結構描述中建立密鑰 CREATE SECRET 在綱要或目錄上
授予他人對密鑰的權限 所有權,或 MANAGE 對祕密、架構或目錄的權限

要授予權限,請使用目錄總管:打開密碼或結構描述,點選 權限 標籤,然後點 選授權。 若要使用 SQL 進行 GRANT,請執行以下操作:

-- Let a job's service principal read every secret in a schema
GRANT USE CATALOG ON CATALOG main TO `etl-service-principal`;
GRANT USE SCHEMA, READ SECRET ON SCHEMA main.orders_app TO `etl-service-principal`;

-- Let the application's developers create secrets in its schema
GRANT USE SCHEMA, CREATE SECRET ON SCHEMA main.orders_app TO `orders-developers`;

請參閱管理 Unity Catalog 中的權限。

閱讀秘密

若要讀取秘密值,你需要擁有該秘密的所有權,或在該秘密、其結構描述或目錄上具有 READ SECRET 權限。

秘密工具程式 (dbutils.secrets)

Azure Databricks 建議dbutils使用秘密,因為它會遮蔽儲存格輸出和日誌中的值。 以下範例讀取資料庫使用者名稱與密碼以設定 JDBC 讀取作業:

username = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_username")
password = dbutils.secrets.get(catalog="main", schema="orders_app", key="db_password")

df = (spark.read
  .format("jdbc")
  .option("url", "<jdbc-url>")
  .option("dbtable", "<table-name>")
  .option("user", username)
  .option("password", password)
  .load()
)

請參見 Secrets 公用程式 (dbutils.secrets)。

REST API

Warning

Unity Catalog REST API 不會遮蔽回傳的值。 審計日誌仍會記錄每一次讀取。 Azure Databricks 改為建議使用 dbutils。

要回傳該值,請在回應中設定 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/main.orders_app.db_password"

列出、更新及刪除秘密

若要更新值,你需要有對秘密項目的 WRITE SECRET 權限。 若要變更其註解或到期日,或將其刪除,你必須擁有該秘密,或對其、其結構描述或其目錄具有 MANAGE。

對於 Azure Key Vault 支援的 schema,在 Azure Key Vault 中更新並刪除祕密。 刪除內容會套用至 Unity Catalog。

目錄檢視器

  1. 在 Catalog Explorer 中,前往結構描述,並在 「概觀」 窗格中按一下 「密鑰」,以列出其密鑰。
  2. 點選你想更改的密鑰。
  3. 在右上角點選 kebab 選單(垂直三點),選擇 編輯 或 刪除。
  4. 要編輯,請輸入新的數值或到期日,然後點擊 確認。 要刪除,請輸入密鑰的完整名稱並點擊 刪除。

秘密工具程式 (dbutils.secrets)

要列出你可以存取的綱要中密鑰,請執行以下操作:

all_secrets = dbutils.secrets.list(catalog="main", schema="orders_app")

REST API

要列出機密,請執行以下操作。 若有更多結果,請將回應的 next_page_token 傳遞為 page_token:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=orders_app" \
  --data-urlencode "page_size=100" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

要更新一個值,請執行以下操作。 只有 update_mask 和請求主體中的欄位會變更:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password?update_mask=*"

要刪除密鑰,請執行以下操作:

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.orders_app.db_password"

為祕密加上標籤

Unity Catalog 的密鑰支援鍵值標籤,例如用來分類密鑰或記錄擁有團隊或成本中心。 請參閱將標籤套用至 Unity Catalog 安全物件。

要在密鑰上新增或移除標籤,您必須擁有該密鑰或具備以下所有權限:

  • APPLY TAG 在秘密上
  • USE SCHEMA 在密碼的父綱要上
  • USE CATALOG 在 Secret 的父目錄集中

要指派受控標籤,您也需要對該受控標籤擁有 ASSIGN 權限。 請參閱 管理受控管標籤的許可權。

若要使用 SQL 新增或移除標籤,請執行以下程序:

SET TAG ON SECRET main.orders_app.db_password cost_center = hr;

UNSET TAG ON SECRET main.orders_app.db_password cost_center;

請參閱 SET TAG 和 UNSET TAG。

若要檢視密鑰上的標籤,請使用下列其中一種:

目錄檢視器

  1. 在目錄總管中,前往結構描述,然後在 概觀 窗格中按一下 密碼。
  2. 按一下該密鑰。 其標籤會出現在「標籤」下的「概覽」標籤頁。

REST API

若要列出密鑰上的標籤,請執行下列步驟。 若有更多結果,請將回應的 next_page_token 傳遞為 page_token:

curl \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/entity-tag-assignments/secrets/main.orders_app.db_password/tags"

CLI

若要列出密鑰上的標籤,請執行下列步驟:

databricks entity-tag-assignments list secrets main.orders_app.db_password

秘密標籤不會出現在 DESCRIBE SECRET輸出中、在取得秘密的 API 回應中、資訊結構表或工作區搜尋中。

稽核祕密存取

系統表記錄 system.access.audit 機密事件。 讀取值會與 action_name = 'getSecret' 一起顯示。 若要列出過去 7 天的 Secret 事件,請執行以下操作:

SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE service_name = 'unityCatalog'
  AND action_name LIKE '%Secret%'
  AND event_date >= current_date() - INTERVAL 7 DAYS
ORDER BY event_time DESC;

請參閱 稽核記錄系統數據表參考。

使用客戶管理的金鑰加密秘密值

Azure Databricks 預設會用 Azure Databricks 管理的鍵加密秘密值。 若要使用自己的金鑰,請在存放祕密的目錄集中設定客戶管理金鑰(CMK)設定。 秘密值會儲存在 Unity Catalog 中,而非 catalog 的儲存位置,因此這適用於任何 catalog,包括具有外部儲存位置的 catalog。 關於需求與設定,請參閱 Unity 目錄的客戶管理的金鑰。

外部秘密值會保留在你的雲端秘密管理器中,並用自己的金鑰加密它們。 目錄中的 CMK 設定不適用於它們。

在 UDF 中使用秘密

Unity Catalog 的 Python 或 Scala UDF 可以使用秘密值,但不會讓呼叫者存取該秘密。 在 UDF 的 SECRETS 子句中宣告機密。 UDF 會根據函式擁有者的權限來讀取它:

  • 擁有者需要對該密鑰具有 READ SECRET 權限,才能建立或取代 UDF。 若業主遺失 READ SECRET,UDF 即告失敗。
  • 呼叫端只需在 UDF 上具備 EXECUTE,且不需要具有該 secret 的任何權限。

UDF 定義必須設 environment_version 為 6 或更高。 在傳統運算上,於標準存取模式下使用 Databricks Runtime 19 及以上版本。 例如,請參見 Python UDF 和 Scala UDF。

會話範圍的 UDF,使用 databricks.secrets.get() 或 com.databricks.Secrets.get(),讀取帶有呼叫者權限的秘密,因此每位呼叫者都需要 READ SECRET。 請參考 Python UDF 和 Scala UDF。

在專用存取模式運算中,你無法直接呼叫這些 UDF。 你可以在 Unity Catalog 的 SQL 函式中呼叫其中一個,作為你用來當成屬性型存取控制(ABAC)欄位遮罩的 SQL 函式,而 Azure Databricks 會在無伺服器運算上強制執行。 請參見 不支援的計算版本。

Warning

只在 UDF 內部使用秘密值。 不要在 UDF 結果中傳回它們。 遮蔽可減少錯誤與日誌中的意外暴露,但無法阻止 UDF 程式碼在查詢結果中回傳秘密。

Limitations

  • 配額:一個結構描述最多可容納 1,000 個密鑰,而一個中繼存放區最多可容納 10,000 個。
  • 無全域搜尋或資訊結構:秘密不會出現在全域搜尋或資訊結構資料表中。 請使用 Catalog Explorer, dbutils或是 REST API。
  • OAuth API 範圍:Unity 目錄的祕密 API 需要 unity-catalog OAuth API 範圍。 該 secrets 範圍僅適用於工作空間的 secret scope。
  • Init 腳本:你不能在全域或叢集範圍的初始化腳本中使用 Unity Catalog 的密鑰。
  • 遠端開發:Databricks Connect 與編譯後的 JAR 執行模式無法讀取 Unity Catalog 的密鑰,因為 dbutils.secrets 需要支援 Databricks 執行環境的筆記本或作業。

其他資源

資源 描述
Unity Catalog 密鑰的最佳實務 依環境、應用程式或團隊整理密鑰,讓工作負載使用密鑰而無須讀取其內容。
祕密管理 比較 Unity Catalog 的密鑰與工作空間的密鑰範圍,看看你可以在哪裡使用兩者各自。