工作空間的祕密範圍是同一工作空間中命名的祕密集合。 祕密範圍權限控制誰能讀取、寫入及管理其中的祕密。 權限適用於整個範圍,而非個別機密,因此能讀取範圍中一個機密的使用者可以讀取所有機密。 若要比較工作區秘密範圍與 Unity Catalog 秘密,請參閱 「選擇存放秘密的位置」。
要使用工作區秘密範圍:
- 建立秘密範圍。
- 在範圍中加入機密。
- 在此範圍上授予權限。
- 在程式碼中參考祕密值,或在 Spark 設定屬性或環境變數中參考。 請參閱在 Spark 組態屬性或環境變數中使用祕密。
Warning
Workspace 管理員、祕密建立者以及已授權的使用者都可以存取並閱讀 Azure Databricks 的祕密。 雖然 Azure Databricks 嘗試在筆記本輸出中遮蔽秘密值,但無法完全阻止這些使用者查看秘密內容。 請務必小心指派秘密訪問許可權,以保護敏感性資訊。
管理秘密範圍
Azure Databricks 建議將祕密範圍對齊於角色或應用程式,而非個別使用者。
秘密範圍有兩種類型:
- Azure 金鑰保存庫 支援:您可以使用 Azure 金鑰保存庫 支援的秘密範圍來參考儲存在 Azure 金鑰保存庫 中的秘密。 以 Azure Key Vault 為後盾的秘密範圍是 金鑰保存庫 的唯讀介面。 你在 Azure 中管理它的祕密。
- Databricks 支援:由 Databricks 支援的秘密範疇會儲存在 Azure Databricks 所擁有和管理的加密資料庫中。
Important
以 Azure Key Vault 為後盾的秘密範圍僅支援 Vault 存取政策權限模型,不支援 Azure 角色型存取控制(RBAC)。 New Azure key vaults 預設使用 Azure RBAC。 如果你的金鑰庫使用 Azure RBAC,請先將其權限模型切換為 Vault 存取政策,再建立由 Azure Key Vault 支援的秘密範圍。
建立秘密範圍之後,您可以指派許可權,授與使用者讀取、寫入及管理秘密範圍的許可權。
建立使用 Azure Key Vault 支援的秘密範圍
在 Azure 入口網站和 Azure Databricks 工作區 UI 中建立以 Azure Key Vault 為後端的秘密範圍。 你也可以使用 Databricks 的 CLI。
Requirements
- 您必須有 Azure 金鑰保存庫實例。 如果您沒有金鑰保存庫實例,請遵循使用 Azure 入口網站 建立 金鑰保存庫 中的指示。
- 您必須在想要用來支援秘密範圍的 Azure 鑰匙庫實例上擁有 鑰匙庫貢獻者、貢獻者或擁有者角色。
備註
建立以 Azure 金鑰庫支援的秘密範疇,需要在 Azure 金鑰庫實例上具有協作者或擁有者角色,先前即使已授予 Azure Databricks 服務金鑰庫的存取權也是如此。
如果金鑰保險庫存在於與 Azure Databricks 工作空間不同的租戶中,建立秘密範圍的 Microsoft Entra ID 使用者必須在金鑰保險庫的租戶中具有建立服務主體的權限。 否則,會發生下列錯誤:
Unable to grant read/list permission to Databricks service principal to KeyVault 'https://xxxxx.vault.azure.net/': Status code 403, {"odata.error":{"code":"Authorization_RequestDenied","message":{"lang":"en","value":"Insufficient privileges to complete the operation."},"requestId":"XXXXX","date":"YYYY-MM-DDTHH:MM:SS"}}
設定 Azure Databricks 的 Azure 金鑰保存庫實例
登入 Azure 入口網站,找到並選擇 Azure key Vault 實例。
在 設定 中,點選存取組態索引標籤。
將 權限模型 設定為 Vault 存取原則。 新的金鑰保存庫預設使用 Azure 角色型存取控制,但由 Azure Key Vault 支援的祕密範圍不支援此控制。
備註
建立由 Azure Key Vault 支援的秘密範圍,會透過 Vault 存取政策授予 Azure Databricks 服務應用程式 ID 的取得與清單權限。
在設定中,選擇網路。
在 防火牆和虛擬網路中, 設定 [允許從: 存取] [允許來自特定虛擬網路和 IP 位址的公用存取。
在 例外狀況 底下,勾選 允許信任的 Microsoft 服務略過此防火牆。
備註
您也可以將 允許存取來源: 設定為 允許來自所有網路的公用存取。
建立以 Azure Key Vault 作為支援的機密範圍
移至
https://<databricks-instance>#secrets/createScope。 將<databricks-instance>替換為 Azure Databricks 部署的工作區 URL。 此 URL 區分大小寫。 例如,在createScope中,scope必須使用大寫S字母。
輸入機密範疇的名稱。 秘密範圍名稱不區分大小寫。
在 [管理主體] 選取 [Creator] 或 [所有工作區使用者],以指定哪些使用者具有秘密範圍的管理許可權。
MANAGE 許可權允許使用者在該範圍內讀取、寫入及授予許可權。 您的帳戶必須有 進階方案 ,才能選擇 [建立者]。
輸入 DNS 名稱 (例如
https://databrickskv.vault.azure.net/) 和資源識別碼,例如:/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/databricks-rg/providers/Microsoft.KeyVault/vaults/databricksKV這些屬性可從您 Azure 入口網站 中 Azure 金鑰保存庫 的 [設定>屬性] 索引標籤取得。
點擊 建立。
使用 Databricks CLI
databricks secrets list-scopes命令來確認已成功建立範圍。
建立 Databricks 支援的機密範圍
使用 Databricks CLI(0.205 版及以上版本)或 Secrets API 建立密碼範圍。
秘密範圍名稱:
- 工作區內必須是唯一的。
- 必須只由英數字元、破折號、底線、
@和句點組成,且不得超過 128 個字元。 - 不區分大小寫。
秘密範圍名稱會視為非敏感性,而且可由工作區中的所有用戶讀取。
若要使用 Databricks CLI 建立範圍:
databricks secrets create-scope <scope-name>
根據預設,系統會使用建立範圍之使用者的 MANAGE 許可權來建立範圍。 建立 Databricks 支援的秘密範圍之後,您可以將秘密新增至其中。
列出秘密範圍
若要使用 CLI 列出工作區中的現有範圍:
databricks secrets list-scopes
您也可以使用 秘密 API列出秘密範圍。
刪除機密範圍
刪除祕密範圍會刪除應用於該範圍的所有祕密和 ACL 的設定。 若要使用 CLI 刪除範圍,請執行下列命令:
databricks secrets delete-scope <scope-name>
您也可以使用 秘密 API 刪除秘密範圍。
管理秘密
秘密是金鑰/值組,會使用秘密範圍內唯一的金鑰名稱來儲存機密數據。
建立秘密的方法取決於您使用的是 Azure 金鑰保存庫 支援的範圍或 Databricks 支援的範圍。
在 Azure 金鑰保存庫 支援的範圍內建立秘密
若要在 Azure Key Vault 中建立秘密,請使用 Azure 入口網站或 Azure 設定秘密 REST API。
在 Databricks 支援的範圍內建立密鑰
可以用 Databricks CLI(版本 0.205 及以上)、筆記本中的 Python Databricks SDK 或 Secrets API 建立秘密。 秘密名稱不區分大小寫。
Databricks 命令行介面
當您在 Databricks 支援的範圍內建立秘密時,您可以使用下列三種方式之一來指定秘密值:
- 將值指定為帶有
--string-value旗標的字串。 - 在互動提示時輸入密碼(單行密碼輸入)。
- 使用標準輸入傳遞秘密(多行秘密)。
例如:
databricks secrets put-secret --json '{
"scope": "<scope-name>",
"key": "<key-name>",
"string_value": "<secret>"
}'
如果您要建立多行密碼,您可以使用標準輸入來傳遞秘密。 例如:
(cat << EOF
this
is
a
multi
line
secret
EOF
) | databricks secrets put-secret <scope-name> <key-name>
適用於 Python 的 Databricks SDK
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
w.secrets.put_secret("<secret_scope>","<key-name>",string_value ="<secret>")
閱讀秘密
用 Databricks CLI(版本 0.205 及以上)讀取密鑰,或在筆記本中用 Secrets 工具(dbutils.secrets)讀取。
Databricks 命令行介面
要使用 Databricks CLI 讀取秘密值,必須解碼 base64 編碼的值。 您可以使用 jq 來擷取值,並將該值 base64 --decode 解碼:
databricks secrets get-secret <scope-name> <key-name> | jq -r .value | base64 --decode
秘密工具程式 (dbutils.secrets)
password = dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")
列出機密
若要列出指定範圍中的秘密:
databricks secrets list-secrets <scope-name>
回應會顯示關於密鑰的中繼資料,例如其金鑰名稱。 若要在筆記本或作業中列出這些元資料,請使用 Secrets 工具(dbutils.secrets)。 例如:
dbutils.secrets.list('my-scope')
刪除秘密
若要使用 Databricks CLI 從一個範圍內刪除機密,請遵循以下步驟:
databricks secrets delete-secret <scope-name> <key-name>
您也可以使用 秘密 API。
若要從 Azure 金鑰保存庫 所支援的範圍中刪除秘密,請使用 Azure SetSecret REST API 或 Azure 入口網站 UI。
管理秘密範圍許可權
預設情況下,建立祕密範圍的使用者對其具有 MANAGE 權限,允許他們讀取該範圍內的祕密、寫入祕密,並管理其權限。
備註
在範圍層級的 ACLs(存取控制列表)屬於機密。 如果您使用 Azure 金鑰保存庫 支援的範圍,則授與範圍存取權的使用者可以存取 Azure 金鑰保存庫 中的所有秘密。 若要限制存取,請使用個別的 Azure 金鑰保存庫實例。
使用 Databricks CLI (版本 0.205 及以上)或 Secrets API 管理秘密範圍權限。 關於秘密權限等級,請參見 秘密 ACLs。
給用戶授予秘密範圍的權限
備註
授予秘密範圍權限需要使用 Premium 方案。
若要使用 Databricks CLI 為用戶授予機密範圍的權限:
databricks secrets put-acl <scope-name> <principal> <permission>
對於已套用許可權的主體提出 PUT 請求會覆寫現有的許可權等級。
欄位 principal 會指定現有的 Azure Databricks 主體。 指定使用者時,使用其電子郵件地址;當指定服務主體時,使用其 applicationId 值;指定群組時,則使用其組名。 如需更多資訊,請參閱 Principal。
例如,要讓像 datascience 這樣的群組讀取作用域中的秘密,授與它 READ:
databricks secrets put-acl <scope-name> <group> READ
檢視秘密範圍許可權
若要檢視指定秘密範圍的所有許可權:
databricks secrets list-acls <scope-name>
若要取得套用至指定機密範疇之主體的機密範疇許可權:
databricks secrets get-acl <scope-name> <principal>
如果指定的主體和範圍沒有 ACL,則此要求會失敗。
刪除秘密範圍許可權
若要刪除套用至指定秘密範圍中某個主體的許可權:
databricks secrets delete-acl <scope-name> <principal>
秘密修訂
將憑證儲存為 Azure Databricks 祕密,有助於在執行筆記本和工作時保護它們。 不過,你仍然有可能不小心印出秘密到標準輸出緩衝區,或在變數指派時顯示該值。
為了避免這種情況,Azure Databricks 會嘗試遮蔽使用 dbutils.secrets.get() 讀取並在 Spark 設定屬性中參考的秘密值。 顯示時,秘密值會取代為 [REDACTED]。
例如,如果您使用 dbutils.secrets.get() 將變數設定為秘密值,然後列印該變數,則該變數會取代為 [REDACTED]。
Warning
修訂僅適用於字面上的秘密值。 秘密遮蔽功能無法防止對秘密字面值的刻意和隨意轉換。 要控制秘密,請使用 存取控制清單 來限制執行指令的權限。 這可防止未經授權的共享筆記本內容存取。
SQL 中的秘密修訂
Azure Databricks 嘗試遮蔽所有呼叫秘密函式的 SQL 資料查詢語言(DQL)指令,包括參考的檢視與使用者自訂函式。 使用 函 secret 式時,輸出會盡可能取代為 [REDACTED] 。 如同筆記本編輯,這只適用於文字值,不適用於已轉換或間接參考的秘密。
對於 SQL 資料操作語言(DML)指令,Azure Databricks 允許在祕密被認為安全的情況下查詢該祕密。 例如,秘密在經過如 sha() 或 aes_encrypt() 這類密碼函數包裹後是安全的,因為這可防止原始值以未加密形式儲存。
SQL 中的秘密驗證
Azure Databricks 也會套用驗證來封鎖可能導致未加密的秘密儲存至數據表的 SQL DML 命令。 查詢分析器會嘗試識別並防止這些案例,這有助於避免以純文本意外儲存敏感性資訊。
其他資源
| 資源 | Description |
|---|---|
| 秘密管理 | 比較工作區機密範圍與 Unity Catalog 機密,看看您可以在哪裡使用各自的機密。 |
| 在 Spark 設定屬性或環境變數中使用秘密值 | 在 Spark 配置屬性和環境變數中引用機密。 |