使用 Azure Key Vault,為 Azure Cosmos DB 帳戶設定客戶自控金鑰
適用於:NoSQL MongoDB Cassandra Gremlin Table
儲存在 Azure Cosmos DB 帳戶中的資料,會使用由 Microsoft 管理的金鑰 (受服務管理的金鑰) 自動進行縝密的加密。 您也可以選擇使用您所管理的金鑰 (客戶自控金鑰或稱為 CMK) 來新增第二層加密。
您必須將客戶管理的金鑰儲存在 Azure Key Vault 中,並且為客戶管理的金鑰已啟用的每個 Azure Cosmos DB 帳戶提供金鑰。 此金鑰會用來加密該帳戶中儲存的所有資料。
注意
如果您想要在現有的 Azure Cosmos DB 帳戶上啟用客戶自控金鑰,可以在這裡參閱連結,以取得詳細資料
警告
針對使用客戶自控金鑰的帳戶中的 Cassandra API 表格,保留下列欄位名稱:
id
ttl
_ts
_etag
_rid
_self
_attachments
_epk
未啟用客戶自控金鑰時,只會保留開頭為 __sys_
的欄位名稱。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
註冊 Azure Cosmos DB 資源提供者
如果尚未註冊 Microsoft.DocumentDB 資源提供者,您應該將註冊此提供者當作第一個步驟。
登入 Azure 入口網站,移至您的 Azure 訂用帳戶,然後在 [設定] 索引標籤下選取 [資源提供者]:
搜尋 Microsoft.DocumentDB 資源提供者。 確認資源提供者標示為已註冊。 如果不是,請選擇資源提供者,然後選取 [註冊]:
設定您的 Azure Key Vault 執行個體
重要
您的 Azure Key Vault 執行個體必須可透過公用網路存取進行存取,或允許受信任的 Microsoft 服務略過其防火牆。 只能透過私人端點存取的執行個體,無法用於裝載客戶自控金鑰。
若要將客戶自控金鑰用於 Azure Cosmos DB,您必須在您打算用來裝載加密金鑰的 Azure Key Vault 執行個體上設定兩個屬性:虛刪除和清除保護。
如果您建立新的 Azure Key Vault 執行個體,請在建立期間啟用這些屬性:
如果您使用現有的 Azure Key Vault 執行個體,您可以查看 Azure 入口網站上的 [屬性] 區段,以確認這些屬性是否已啟用。 如果這些屬性皆未啟用,請參閱下列其中一篇文章中的「啟用虛刪除」和「啟用清除保護」小節:
選擇慣用的安全性模型
一旦啟用清除保護和虛刪除後,您就可以在 [存取原則] 索引標籤上,選擇您要使用的慣用權限模型。 預設會設定存取原則,但也支援 Azure 角色型存取控制。
必須提供必要的權限,才能讓 Cosmos DB 使用您的加密金鑰。 此步驟會根據 Azure Key Vault 使用存取原則或角色型存取控制而有所不同。
注意
請務必注意,一次只能使用一個安全性模型,因此,如果 Azure Key Vault 設定為使用存取原則,則不需要植入角色型存取控制,反之亦然
新增存取原則
在此差異中,使用 Azure Cosmos DB 主體建立具有適當權限的存取原則。
在 Azure 入口網站中,移至您打算用來裝載加密金鑰的 Azure Key Vault 執行個體。 從左側功能表中選取 [存取原則]:
選取+ 新增存取原則。
在 [金鑰權限] 下拉式功能表中,選取 [取得]、[將金鑰解除包裝] 和 [包裝金鑰] 權限:
在 [選取主體] 底下,選取 [未選取任何項目]。
搜尋 Azure Cosmos DB 主體並加以選取 (您也可以用應用程式識別碼
a232010e-820c-4083-83bb-3ace5fc29d0b
以便搜尋各個 Azure 區域,不過 Azure Government 區域除外,其應用程式識別碼為57506a73-e302-42a9-b869-6f12d9ec29e9
)。提示
這會在您的 Azure Key Vault 存取原則中註冊 Azure Cosmos DB 第一方身分識別。 如果 Azure Cosmos DB 主體不在清單中,您可能需要重新註冊 Microsoft.DocumentDB 資源提供者。
選擇底部的 [選取]。
選取 [新增] 以新增存取原則。
選取 Key Vault 執行個體上的 [儲存],以儲存所有變更。
新增角色型存取控制角色
在 Azure 入口網站中,移至您打算用來裝載加密金鑰的 Azure Key Vault 執行個體。 從左側功能表中選取 [存取控制 (IAM)],然後選取 [授與此資源的存取權]。
搜尋 Key Vault 管理員角色,並將其指派給您自己。 此指派方式是先從清單中搜尋角色名稱,然後按一下 [成員] 索引標籤。在索引標籤上的選項中選取 [使用者、群組或服務主體] 選項,然後查閱您的 Azure 帳戶。 選取帳戶之後,即可指派角色。
然後,必須將必要的權限指派給 Cosmos DB 的主體。 因此,如同上一個角色指派,移至指派頁面,但這次要尋找「Key Vault Crypto 服務加密使用者」角色,並在 [成員] 索引標籤上尋找 Cosmos DB 的主體。 若要尋找主體,請搜尋 Azure Cosmos DB 主體並將其選取。
重要
在 Azure Government 區域中,應用程式識別碼為
57506a73-e302-42a9-b869-6f12d9ec29e9
。選取 [檢閱 + 指派],即可將角色指派給 Cosmos DB。
驗證角色是否已正確設定
接下來,使用存取控制頁面來確認所有角色都已正確設定。
指派角色之後,請在 [存取控制 IAM] 頁面上選取 [檢視此資源的存取權],以確認所有項目都已正確設定。
在該頁面上,將範圍設定為 [此資源],並確認您具有 Key Vault 管理員角色,且 Cosmos DB 主體具有 Key Vault Crypto 加密使用者角色。
在 Azure Key Vault 中產生金鑰
在這裡,使用 Azure Key Vault 建立新的金鑰,並擷取唯一識別碼。
在 Azure 入口網站中,移至您打算用來裝載加密金鑰的 Azure Key Vault 執行個體。 然後,從左側功能表中選取 [金鑰]:
選取 [產生/匯入]、提供新金鑰的名稱,然後選取 RSA 金鑰大小。 建議至少要有 3072,以達到最佳安全性。 然後,選取 [建立]:
提示
或者,您也可以使用 Azure CLI 來產生金鑰:
az keyvault key create \ --vault-name <name-of-key-vault> \ --name <name-of-key>
如需使用 Azure CLI 管理金鑰保存庫的詳細資訊,請參閱使用 Azure CLI 管理 Azure Key Vault。
在金鑰建立後,選取新建立的金鑰,然後選取其目前的版本。
複製金鑰的 [金鑰識別碼],但最後一個正斜線後面的部分除外:
建立新的 Azure Cosmos DB 帳戶
使用 Azure 入口網站或 Azure CLI 建立新的 Azure Cosmos DB 帳戶。
當您從 Azure 入口網站建立新的 Azure Cosmos DB 帳戶時,請在 [加密] 步驟中選擇 [客戶管理的金鑰]。 在 [金鑰 URI] 欄位中,貼上您在先前的步驟中複製的 Azure Key Vault 金鑰的 URI/金鑰識別碼:
重要
視您的網路設定而定,您可能需要允許從其他 Azure 服務存取 Azure Cosmos DB。
在 Azure Key Vault 存取原則中使用受控識別
此存取原則能確保您的 Azure Cosmos DB 帳戶可以存取加密金鑰。 存取原則會透過授與特定 Microsoft Entra 身分識別的存取權來實作。 支援兩種類型的身分識別:
- Azure Cosmos DB 的第一方身分識別可以用於授與 Azure Cosmos DB 服務的存取權。
- Azure Cosmos DB 帳戶的受控識別可以專門用於授與您帳戶的存取權。
搭配連續備份使用客戶自控金鑰
您可以使用 Azure CLI 或 Azure Resource Manager 範本來建立連續備份帳戶。
目前,僅支援使用者指派的受控識別來建立連續備份帳戶。
建立帳戶之後,您可以將身分識別更新為系統指派的受控識別。
或者,使用者也可以先建立使用定期備份模式的系統身分識別,然後使用下列指示:將 Azure Cosmos DB 帳戶從定期備份遷移至連續備份模式
還原已設定受控識別的連續帳戶
還原要求中需要使用者指派的身分識別,因為來源帳戶受控識別 (使用者指派和系統指派的身分識別) 無法自動傳送至目標資料庫帳戶。
客戶自控金鑰與雙重加密
使用客戶自控金鑰時,您儲存在 Azure Cosmos DB 帳戶中的資料最後會加密兩次:
- 透過使用 Microsoft 管理的金鑰執行的預設加密之後。
- 透過使用客戶自控金鑰執行的額外加密一次之後。
雙重加密僅適用於主要 Azure Cosmos DB 交易式儲存體。 某些功能牽涉到將資料內部複寫至未提供雙重加密的第二層儲存體,即便使用客戶自控金鑰也如此。 這些功能包括:
金鑰輪替
您可以透過兩種方式來輪替 Azure Cosmos DB 帳戶所使用的客戶自控金鑰。
建立 Azure Key Vault 中所使用目前金鑰的新版本:
更新您帳戶上的金鑰 URI,以將目前使用的金鑰交換為不同的金鑰。 從 Azure 入口網站前往您的 Azure Cosmos DB 帳戶,然後從左側功能表中選取 [資料加密]:
接著,用您想要使用的新金鑰取代金鑰 URI,然後選取 [儲存]:
以下是透過 PowerShell 達到相同結果的方法:
# Variable for resource group name $RESOURCE_GROUP_NAME = "<resource-group-name>" # Variable for account name $ACCOUNT_NAME = "<globally-unique-account-name>" # Variable for new key URI in the key vault $NEW_KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.net/keys/<new-key-name>" $parameters = @{ ResourceGroupName = $RESOURCE_GROUP_NAME Name = $ACCOUNT_NAME ResourceType = "Microsoft.DocumentDb/databaseAccounts" } $ACCOUNT = Get-AzResource @parameters $ACCOUNT.Properties.keyVaultKeyUri = $NEW_KEY_VAULT_KEY_URI $ACCOUNT | Set-AzResource -Force
在 Azure Key Vault 稽核記錄不再顯示 Azure Cosmos DB 中屬於先前的金鑰或金鑰版本的活動之後,便可停用該金鑰或金鑰版本。 金鑰輪替 24 小時後,應該就不會有任何活動以先前的金鑰或金鑰版本進行。
只要先前的金鑰未停用或刪除,Azure Key Vault 中的金鑰自動輪替就會受到支援。 內部系統需要一些時間來掌握新版本的金鑰,然後驗證帳戶未處於撤銷狀態或轉換,以啟用客戶管理的金鑰。
錯誤處理
如果在 Azure Cosmos DB 中發生客戶自控金鑰的錯誤時,Azure Cosmos DB 會在回應中傳回錯誤詳細資料及 HTTP 子狀態碼。 您可以使用 HTTP 子狀態碼來偵錯問題的根本原因。 若要取得支援的 HTTP 子狀態碼清單,請參閱 Azure Cosmos DB 的 HTTP 狀態碼一文。
常見問題集
以下是在 Azure Cosmos DB 中設定客戶自控金鑰的常見問題。
啟用客戶自控金鑰是否會收取額外費用?
否,啟用這項功能不需要任何費用。
客戶自控金鑰對於容量規劃有何影響?
使用客戶管理的金鑰時,您的資料庫作業所使用的要求單位將會增加,以反映執行資料加密和解密所需的額外處理。 額外的 RU 耗用可能會導致您所佈建的容量使用率稍微提高。 使用下表來取得指引:
作業類型 | 要求單位增加 |
---|---|
讀數 (依識別碼擷取項目) | 每項作業 + 5% |
任何寫入作業 | 每項作業 + 6% | 每個索引屬性大約 + 0.06 RU |
查詢、讀取變更摘要或衝突摘要 | 每項作業 + 15% |
哪些資料會使用客戶管理的金鑰進行加密?
儲存在 Azure Cosmos DB 帳戶中的所有資料都會使用客戶管理的金鑰進行加密,但下列中繼資料除外:
現有的 Azure Cosmos DB 帳戶是否支援客戶管理的金鑰?
是。 您可以參考如何為現有的 Azure Cosmos DB 帳戶設定客戶自控金鑰
是否可以搭配使用客戶自控金鑰與 Azure Cosmos DB 分析存放區?
可以,Azure Synapse Link 僅支援使用您的 Azure Cosmos DB 帳戶受控識別來設定客戶自控金鑰。 您必須在您的 Azure Key Vault 存取原則中使用 Azure Cosmos DB 帳戶的受控識別,才能在您的帳戶上啟用 Azure Synapse Link。 如需如何啟用受控識別並將其用於存取原則的作法指南,請參閱使用受控識別從 Azure Cosmos DB 存取 Azure Key Vault。
未來是否預計要支援比帳戶層級金鑰更精細的細微性?
目前無此計劃,但正在考量容器層級金鑰。
如何判斷我的 Azure Cosmos DB 帳戶是否已啟用客戶管理的金鑰?
從 Azure 入口網站前往您的 Azure Cosmos DB 帳戶,並查看左側功能表中的 [資料加密] 項目;如果此項目存在,表示您的帳戶上已啟用客戶自控金鑰:
您也可以透過程式設計方式擷取 Azure Cosmos DB 帳戶的詳細資料,並確認 keyVaultKeyUri
屬性是否存在。
客戶自控金鑰對定期備份有何影響?
Azure Cosmos DB 會對儲存在您帳戶中的資料進行定期和自動備份。 此作業會備份已加密的資料。
若要順利還原定期備份,必須符合下列條件:
- 一定要有備份時所使用的加密金鑰,而且必須可在 Azure Key Vault 中使用。 此條件需要並未撤銷的金鑰,且備份時所使用的金鑰版本仍是啟用狀態。
- 如果您使用存取原則中系統指派的受控識別,請暫時將存取權授與 Azure Cosmos DB 的第一方身分識別,才能還原您的資料。 之所以有此需求是因為系統指派的受控識別專屬於帳戶,因此無法在目標帳戶中重複使用。 資料完全還原至目標帳戶之後,您即可透過 Key Vault 存取原則設定您要得識別設定並移除第一方身分識別。
客戶自控金鑰對連續備份有何影響?
Azure Cosmos DB 可讓您選擇在帳戶上設定連續備份。 使用連續備份,您即可將資料還原至過去 30 天內的任意時間點。 若要在啟用客戶自控金鑰的帳戶上使用連續備份,則您必須在 Key Vault 存取原則中使用系統指派或使用者指派的受控識別。 使用連續備份的帳戶目前不支援 Azure Cosmos DB 第一方身分識別。
已啟用客戶自控金鑰的帳戶在更新使用者指派身分識別時的必要步驟。
- 將使用者指派的身分識別新增至 Cosmos DB 帳戶,並在金鑰保存庫存取原則中授與權限。
- 透過 Azure CLI 或 ARM 將使用者指派設為預設身分識別。
az cosmosdb update --resource-group MyResourceGroup --name MyAccountName --default-identity UserAssignedIdentity=/subscriptions/MySubscriptionId/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyUserAssignedIdentity
若要順利執行時間點還原,必須符合下列條件:
- 一定要有備份時所使用的加密金鑰,而且必須可在 Azure Key Vault 中使用。 此需求表示金鑰並未撤銷,且備份時所使用的金鑰版本仍是啟用狀態。
- 您必須確定原始來源帳戶上所使用的使用者指派受控識別仍會在 Key Vault 存取原則中宣告。
重要
如果您在刪除您的帳戶之前撤銷加密金鑰,您的帳戶備份可能最多會遺失在撤銷前 1 小時內寫入的資料。
如何撤銷加密金鑰?
金鑰撤銷可藉由停用最新版本的金鑰來完成:
或者,若要撤銷 Azure Key Vault 執行個體中的所有金鑰,您可以刪除為 Azure Cosmos DB 主體授與的存取原則:
客戶管理的金鑰撤銷後,可以執行哪些作業?
加密金鑰撤銷後,唯一可行的作業為刪除帳戶。
將新的受控識別指派給還原的資料庫帳戶,以繼續存取資料庫帳戶或復原其存取權
每當我們將使用者指派的身分識別指派給帳戶時,ARM 就會將要求轉送給受控服務識別來建立此連結,讓使用者指派的身分識別繫結至指定的 Cosmos DB 帳戶。 目前,我們會在 CMK + 使用者指派身分識別的還原期間 (適用於連續和定期備份還原),將來源資料庫帳戶的使用者身分識別資訊轉交給目標資料庫帳戶,
因為身分識別中繼資料會與來源資料庫帳戶繫結,而還原工作流程不會將身分識別的範圍重新設定為目標資料庫帳戶。 這會導致還原的資料庫帳戶處於不良狀態,並在刪除來源帳戶且身分識別的更新時間過期之後變得無法存取。
指派新受控識別的步驟:
下一步
- 深入了解 Azure Cosmos DB 中的資料加密。