使用 Azure 受控 HSM Key Vault，為 Azure Cosmos DB 帳戶設定客戶自控金鑰

適用於：NoSQL MongoDB Cassandra Gremlin Table

請參閱連結使用 Azure Key Vault 設定客戶自控金鑰

注意

目前，客戶管理的金鑰僅適用於新的 Azure Cosmos DB 帳戶。 您應在帳戶建立期間進行其設定。

為您的 Azure 訂用帳戶註冊 Azure Cosmos DB 資源提供者

1. 登入 Azure 入口網站，移至您的 Azure 訂用帳戶，然後在 [設定] 索引標籤下選取 [資源提供者]：

   

2. 搜尋 Microsoft.DocumentDB 資源提供者。 確認資源提供者標示為已註冊。 如果不是，請選擇資源提供者，然後選取 [註冊]：

   

設定 Azure 受控 HSM Key Vault

若要將客戶自控金鑰用於 Azure Cosmos DB，您必須在您打算用來裝載加密金鑰的 Azure Key Vault 執行個體上設定兩個屬性：虛刪除和清除保護。

因為預設會開啟虛刪除，所以必須啟用清除保護。 建立受控 HSM 時，請使用下列 CLI 命令：

objectId = az ad signed-in-user show --query id -o tsv
az keyvault create --hsm-name $hsmName --resource-group $rgName --location $location --enable-purge-protection true --administrators $objectId --retention-days 7

如果您使用現有的 Azure 受控 HSM Key Vault 執行個體，您可以使用以下命令查看 [屬性] 區段，以確認這些屬性是否已啟用：

az keyvault show $hsmName $rgName

如果未開啟清除保護，可以使用下列命令：

az keyvault update-hsm --enable-purge-protection true --hsm-name $hsmName --resource-group $rgName

如需瞭解適用於受控 HSM 之 CLI 命令的詳細資訊，請參閱下列 Azure Key Vault

建立加密金鑰並指派對應者角色

啟用受控 HSM 之後，必須建立要用於 CMK 帳戶的金鑰。 為此，需要將「受控 HMS 密碼編譯用戶」指派給系統管理員。 若要深入瞭解 RBAC (角色型存取控制) 如何與受控 HSM 搭配運作，請參閱下列文章：受控 HSM 本機 RBAC 內建角色 - Azure Key Vault | Microsoft Learn (英文) 和 Azure 受控 HSM 存取控制 | Microsoft Learn (英文)

objectId = az ad signed-in-user show --query id -o tsv
$keyName = "Name of your key"
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto User" --assignee $objectId --scope /keys
az keyvault key create --hsm-name $hsmName --name $keyName --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

現在已建立金鑰，必須將對應者角色指派給 Cosmos DB 主體識別碼或 Azure 受控識別，然後才能佈建帳戶。 使用「受控 HSM 密碼編譯服務加密使用者」角色，因為該角色剛好包含了使用 CMK 帳戶所需要的三個權限，即：取得、包裝和解除包裝。 這些許可權的有效範圍也僅限於儲存在 Azure 受控 HSM 上的金鑰。

無 Azure 受控識別：

$cosmosPrincipal = az ad sp show --id a232010e-820c-4083-83bb-3ace5fc29d0b --query id -o tsv
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $cosmosPrincipal --scope /keys
$keyURI = "https://{0}.managedhsm.azure.net/keys/{1}" -f $hsmName, $keyName
az cosmosdb create -n $cosmosName -g $rgName --key-uri $keyURI

有 Azure 受控識別：

$identityResourceID = az identity show -g $rgName -n $identityName --query id -o tsv
$identityPrincipal = az identity show -g $rgName -n $identityName --query principalId -o tsv
$defaultIdentity = "UserAssignedIdentity={0}" -f $identityResourceID
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $cosmosPrincipal --scope /keys
$keyURI = "https://{0}.managedhsm.azure.net/keys/{1}" -f $hsmName, $keyName
az cosmosdb create -n $cosmosName -g $rgName --key-uri $keyURI --assign-identity $identityResourceID --default-identity $defaultIdentity

這會佈建 Cosmos DB CMK 帳戶，其中包含儲存在 Azure 受控 HSM Key Vault 上的密鑰。

切換至系統指派的受控識別。

Cosmos DB 支援針對 CMK Cosmos DB 帳戶使用系統指派的受控識別。 如需瞭解系統指派的受控識別 CMK 之詳細資訊，請參閱為 Azure Cosmos DB 帳戶設定客戶自控金鑰

執行下列命令，從預設的身分識別切換至系統指派的受控識別：

az cosmosdb identity assign -n $cosmosName -g $rgName
$principalMSIId = az cosmosdb identity show -n $cosmosName -g $rgName --query principalId -o tsv
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $principalMSIId --scope /keys
az cosmosdb update --resource-group $rgName --name $cosmosName --default-identity "SystemAssignedIdentity"

您可以選擇性地移除對 Cosmos DB 主體識別碼或 Azure 受控識別的原始角色指派。

az keyvault role assignment delete --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $cosmosPrincipal --scope /keys

下一步

• 深入了解 Azure Cosmos DB 中的資料加密。
• 取得在 Azure Cosmos DB 中安全存取資料的概觀。