你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

用于 Azure Fluid Relay 加密的客户管理的密钥

2025-10-04

可以使用自己的加密密钥来保护 Azure Fluid Relay 资源中的数据。指定客户管理的密钥 (CMK) 时，该密钥用于保护和控制对数据加密密钥的访问。 CMK 可以更灵活地管理访问控制。

必须使用以下某种 Azure 密钥存储来存储你的 CMK：

必须创建新的 Azure Fluid Relay 资源才能启用 CMK。无法更改现有 Fluid Relay 资源的 CMK 启用/禁用。

此外，Fluid Relay 的 CMK 依赖于托管标识，启用 CMK 时需要为 Fluid Relay 资源分配一个托管标识。仅用户分配的标识可用于 Fluid Relay 资源 CMK。有关托管标识的详细信息，请参阅此处。

尚无法通过 Azure 门户使用 CMK 配置 Fluid Relay 资源。

使用 CMK 配置 Fluid Relay 资源时，Azure Fluid Relay 服务会在存储 Fluid 会话工件的 Azure 存储帐户范围内配置适当的 CMK 加密设置。有关 Azure 存储中的 CMK 的详细信息，请参阅此处。

若要验证 Fluid Relay 资源是否正在使用 CMK，可以发送 GET 检查资源的属性，查看资源是否具有有效的非空属性 encryption.customerManagedKeyEncryption。

Prerequisites

在 Azure Fluid Relay 资源上配置 CMK 之前，必须满足以下先决条件：

密钥必须存储在 Azure Key Vault 中。
密钥必须是 RSA 密钥而不是 EC 密钥，因为 EC 密钥不支持包装和解包。
必须在步骤 1 中创建对密钥保管库具有必要权限（获取、包装和解包）的用户分配的托管标识。有关详细信息，请参阅此处。在 AKV 中的密钥权限下授予 GET、WRAP 和 UNWRAP。
Azure 密钥库、用户分配的标识和 Fluid Relay 资源必须位于同一区域和同一Microsoft Entra 租户中。
Key Vault 和密钥必须在 Fluid Relay 资源的整个生存期内保持活动状态。
- 在删除所有关联的 Fluid Relay 服务之前，请勿删除或禁用密钥保管库或密钥。否则，Fluid Relay 资源将进入 不可用状态。在这种情况下，首先需要恢复密钥或密钥保管库。
如果向密钥 URL 提供特定密钥版本， 则仅使用该版本 用于 CMK 目的。如果以后添加新密钥版本，则必须在 Fluid Relay 资源的 CMK 设置中手动更新密钥 URL，以使新版本生效。如果删除或禁用指定的密钥版本而不更新资源以使用有效版本，Fluid Relay 服务将失败。
若要允许 Fluid Relay 服务从密钥保管库中自动使用密钥的最新密钥版本，可以在加密密钥 URL 中省略密钥版本。此设置使 Fluid Relay Service 的存储依赖项每天检查密钥保管库中是否有新版本的客户管理的密钥，并将密钥自动更新到最新版本。但是，你仍负责管理和轮换 Key Vault 中的密钥版本。
- 由于资源限制，切换到此自动更新设置可能会失败。如果发生这种情况，请显式指定密钥版本，并为新的密钥版本对 Fluid Relay 资源执行手动更新。

使用 CMK 创建 Fluid Relay 资源

PUT https://management.azure.com/subscriptions/<subscription ID>/resourceGroups/<resource group name> /providers/Microsoft.FluidRelay/fluidRelayServers/< Fluid Relay resource name>?api-version=2022-06-01 @"<path to request payload>"

请求有效负载格式：

{
    "location": "<the region you selected for Fluid Relay resource>",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            “<User assigned identity resource ID>": {}
        }
    },
    "properties": {
       "encryption": {
            "customerManagedKeyEncryption": {
                "keyEncryptionKeyIdentity": {
                    "identityType": "UserAssigned",
                    "userAssignedIdentityResourceId":  "<User assigned identity resource ID>"
                },
                "keyEncryptionKeyUrl": "<key identifier>"
            }
        }
    }
}

示例 userAssignedIdentities 和 userAssignedIdentityResourceId/subscriptions/ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testUserAssignedIdentity

示例 keyEncryptionKeyUrl：https://test-key-vault.vault.azure.net/keys/testKey/testKeyVersionGuid

Notes:

Identity.type 必须是 UserAssigned。它是分配给 Fluid Relay 资源的托管标识的标识类型。
Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.identityType 必须是 UserAssigned。它是应用于 CMK 的托管标识的标识类型。
虽然可以在 Identity.userAssignedIdentities 中指定多个用户标识，但只有一个分配给 Fluid Relay 资源的用户标识用于 CMK 访问密钥保管库进行加密。
Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.userAssignedIdentityResourceId 是应用于 CMK 的用户分配标识的资源 ID。请注意，它应是 Identity.userAssignedIdentities 中的标识之一（必须先将标识分配给 Fluid Relay 资源，然后才能将其用于 CMK）。此外，它应对密钥（由 keyEncryptionKeyUrl 提供）具有必要的权限。
Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyUrl 是用于 CMK 的密钥标识符。

首先需要安装 Azure Fluid Relay 模块。

Install-Module Az.FluidRelay

并确保完成所有先决条件步骤。

创建启用了 CMK 的 Fluid Relay Service 的示例：

New-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -Location "<region>" -KeyEncryptionKeyIdentityType UserAssigned -KeyEncryptionKeyIdentityUserAssignedIdentityResourceId "<user assigned resource id>" -CustomerManagedKeyEncryptionKeyUrl "<key URL>" -UserAssignedIdentity "<user assigned resource id>"

有关命令的详细信息，请参阅 New-AzFluidRelayServer

Notes:

KeyEncryptionKeyIdentityType UserAssigned自 CMK 不支持标识以来SystemAssigned。它指示用于 Customer-Managed 密钥（CMK）加密的标识类型。
虽然可以在参数中 UserAssignedIdentity 指定多个标识， 但只有 定义的 KeyEncryptionKeyIdentityUserAssignedIdentityResourceId 标识用于访问用于 CMK 加密的 Key Vault。
字段 KeyEncryptionKeyIdentityUserAssignedIdentityResourceId 应设置为用于 CMK 访问的用户分配标识 的资源 ID 。
- 此标识必须已在字段中列出 UserAssignedIdentity 。
- 此外，它还需要对在中指定的 CustomerManagedKeyEncryptionKeyUrl密钥具有必要的权限。
CustomerManagedKeyEncryptionKeyUrl 是用于 CMK 的 密钥标识符 。

若要使用 Azure CLI 创建启用了 CMK 的 Fluid Relay，首先需要安装 fluid-relay 扩展。请参阅说明。

并确保完成所有先决条件步骤。

创建启用了 CMK 的 Fluid Relay Service 的示例：

az fluid-relay server create --server-name <Fluid Relay Service name> --resource-group <resource group name> --identity '{"type":"UserAssigned","user-assigned-identities":{"<user assigned resource id>":{}}}' --key-identity '{"identity-type":"UserAssigned","user-assigned-identities":"<user assigned resource id>"}' --key-url "<key URL>" --location <location> --sku <standard or basic>

有关命令的详细信息，请参阅 az fluid-relay server create

Notes:

这些参数必须以 字符串化 JSON 格式提供。
- identity、key-identity
type下面的identity字段必须是UserAssigned。它指定分配给 Fluid Relay 资源的托管标识的标识类型。
identity-type下面的key-identity字段也必须是UserAssigned。它指示用于 Customer-Managed 密钥（CMK）加密的标识类型。
虽然可以在参数中 identity 指定多个标识， 但只有 定义的 key-identity 标识用于访问用于 CMK 加密的 Key Vault。
user-assigned-identities下面的key-identity字段应设置为用于 CMK 访问的用户分配标识的资源 ID。
- 此标识必须已在字段中列出 identity 。
- 此外，它还需要对在中指定的 key-url密钥具有必要的权限。
key-url 是用于 CMK 的 密钥标识符 。

更新现有 Fluid Relay 资源的 CMK 设置

可以更新现有 Fluid Relay 资源的以下 CMK 设置：

更改用于访问密钥加密密钥的标识。
更改密钥加密密钥标识符（密钥 URL）。
更改密钥加密密钥的密钥版本。

启用后，无法在现有 Fluid Relay 资源上禁用 CMK。

在更新密钥加密密钥（按标识符或版本）之前，请确保 之前密钥版本仍处于启用状态，并且密钥保管库中尚未过期。否则，更新作将失败。

使用 update 命令时，只能指定已更改的参数，可以省略未更改的参数。

所有更新都必须满足本页中所述的先决条件。

请求 URL：

PATCH https://management.azure.com/subscriptions/<subscription id>/resourceGroups/<resource group name>/providers/Microsoft.FluidRelay/fluidRelayServers/<fluid relay server name>?api-version=2022-06-01 @"path to request payload"

用于更新密钥加密密钥 URL 的请求有效负载示例：

{
    "properties": {
       "encryption": {
            "customerManagedKeyEncryption": {
                "keyEncryptionKeyUrl": "https://test_key_vault.vault.azure.net/keys/testKey /xxxxxxxxxxxxxxxx"
            }
        }
    }
}

首先需要安装 Azure Fluid Relay 模块。

Install-Module Az.FluidRelay

在更新期间，只需提供需要更改的参数。

更新加密密钥 URL

Update-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -CustomerManagedKeyEncryptionKeyUrl "<new key URL>"

更新 CMK 的分配标识

Update-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -KeyEncryptionKeyIdentityUserAssignedIdentityResourceId "<new user assigned resource id>"

有关命令的详细信息，请参阅 Update-AzFluidRelayServer

更新加密密钥 URL

az fluid-relay server update --server-name <Fluid Relay Service name> --resource-group <resource group> --key-url <new key URL>

更新 identity 并 key-identity 遵循与创建资源时相同的格式。但是，在更新期间，只需提供需要更改的参数。

更新 CMK 的分配标识

az fluid-relay server update --server-name <Fluid Relay Service name> --resource-group <resource group> --key-identity '{"user-assigned-identities":"<new user assigned resource id>"}'

有关命令的详细信息，请参阅 az fluid-relay server update

删除启用了 CMK 的 Azure Fluid Relay 资源

删除启用了 Customer-Managed 密钥（CMK）的 Azure Fluid Relay 资源遵循删除标准 Fluid Relay 资源的过程。但是，必须确保 Fluid Relay 资源在 CMK 依赖项之前被删除，例如加密密钥、Key Vault 和任何用户分配的托管标识。

如果在同一资源组中预配 Fluid Relay 资源及其 CMK 依赖项（Key Vault 和用户分配的标识），则必须首先显式删除 Fluid Relay 资源。否则，尝试一次性删除整个资源组将失败，因为删除其依赖项后无法删除 Fluid Relay 资源。

Troubleshooting

错误：配置 CMK 时发生意外错误

确保配置满足先决条件部分中列出的所有要求。
检查是否已在 Azure Key Vault 中启用防火墙规则。如果是，请启用“允许受信任的Microsoft服务绕过此防火墙”选项。请参阅仅启用 Key Vault 防火墙的受信任服务
对于现有的 Fluid Relay 资源，请验证密钥（或特定密钥版本（如果 CMK 设置中指定了密钥）是否仍在 Key Vault 中启用且 未过期 。

另请参阅

反馈

此页面是否有帮助？