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
- 必須為 Unity 目錄啟用此工作區。 請參閱什麼是 Unity Catalog?。
- 要使用
dbutils讀取秘密,請使用環境 版本 4 及以上的無伺服器筆記本與工作,或是執行 Databricks Runtime 17.3 LTS 及以上版本的傳統運算。 Azure Databricks 建議使用無伺服器或標準存取模式。 - 關於在 UDF 中使用密鑰,請參見 Use secrets in UDFs。
建立密碼
秘密存在於結構描述中。 在一個只有需要的主體身分能存取的結構描述中建立祕密。 要決定如何將祕密分組成結構,請參見「依誰需要這些祕密來分組」。
結構描述會儲存 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;
目錄檢視器
- 在你的 Azure Databricks 工作區中,點選目錄以開啟目錄總管。
- 前往您要建立密鑰的結構描述。
- 按一下 建立 > 密鑰。
- 輸入 一個名字 和 數值。 可選擇性地加上 註解 和 有效期限。 如果秘密過期,目錄瀏覽器會顯示警告。
- 點擊 建立。
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 秘密。
- 在 Azure Key Vault 中建立作為該結構描述後盾的祕密。
- 請依名稱閱讀這個祕密。 請參見 閱讀一個秘密。
授權存取機密
授予符合每個主體所需操作的特權。 除了 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`;
閱讀秘密
若要讀取秘密值,你需要擁有該秘密的所有權,或在該秘密、其結構描述或目錄上具有 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。
目錄檢視器
- 在 Catalog Explorer 中,前往結構描述,並在 「概觀」 窗格中按一下 「密鑰」,以列出其密鑰。
- 點選你想更改的密鑰。
- 在右上角點選 kebab 選單(垂直三點),選擇 編輯 或 刪除。
- 要編輯,請輸入新的數值或到期日,然後點擊 確認。 要刪除,請輸入密鑰的完整名稱並點擊 刪除。
秘密工具程式 (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;
若要檢視密鑰上的標籤,請使用下列其中一種:
目錄檢視器
- 在目錄總管中,前往結構描述,然後在 概觀 窗格中按一下 密碼。
- 按一下該密鑰。 其標籤會出現在「標籤」下的「概覽」標籤頁。
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-catalogOAuth API 範圍。 該secrets範圍僅適用於工作空間的 secret scope。 - Init 腳本:你不能在全域或叢集範圍的初始化腳本中使用 Unity Catalog 的密鑰。
-
遠端開發:Databricks Connect 與編譯後的 JAR 執行模式無法讀取 Unity Catalog 的密鑰,因為
dbutils.secrets需要支援 Databricks 執行環境的筆記本或作業。
其他資源
| 資源 | 描述 |
|---|---|
| Unity Catalog 密鑰的最佳實務 | 依環境、應用程式或團隊整理密鑰,讓工作負載使用密鑰而無須讀取其內容。 |
| 祕密管理 | 比較 Unity Catalog 的密鑰與工作空間的密鑰範圍,看看你可以在哪裡使用兩者各自。 |