Skip to content

Commit 5b75406

Browse files
JillGrant615JillGrant615
authored
Merge pull request #302544 from yunho-microsoft/yunho/enhanceCmkDocs
Fluid Relay: improve CMK documentation
2 parents d3888df + df7d990 commit 5b75406

File tree

1 file changed

+168
-51
lines changed

1 file changed

+168
-51
lines changed

‎articles/azure-fluid-relay/concepts/customer-managed-keys.md

Lines changed: 168 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -8,102 +8,219 @@ ms.topic: reference
88

99
# Customer-managed keys for Azure Fluid Relay encryption
1010

11-
You can use your own encryption key to protect the data in your Azure Fluid Relay resource. When you specify a customer-managed key (CMK), that key is used to protect and control access to the key that encrypts your data. CMK offers greater flexibility to manage access controls.
11+
You can use your own encryption key to protect the data in your Azure Fluid Relay resource. When you specify a customer-managed key (CMK), that key is used to protect and control access to the key that encrypts your data. CMK offers greater flexibility to manage access controls.
1212

13-
You must use one of the following Azure key stores to store your CMK:
14-
- [Azure Key Vault](/azure/key-vault/general/overview)
13+
You must use one of the following Azure key stores to store your CMK:
14+
- [Azure Key Vault](/azure/key-vault/general/overview)
1515
- [Azure Key Vault Managed Hardware Security Module (HSM)](/azure/key-vault/managed-hsm/overview)
1616

17-
You must create a new Azure Fluid Relay resource to enable CMK. You cannot change the CMK enablement/disablement on an existing Fluid Relay resource.
17+
You must create a new Azure Fluid Relay resource to enable CMK. You cannot change the CMK enablement/disablement on an existing Fluid Relay resource.
1818

1919
Also, CMK of Fluid Relay relies on Managed Identity, and you need to assign a managed identity to the Fluid Relay resource when enabling CMK. Only user-assigned identity is allowed for Fluid Relay resource CMK. For more information about managed identities, see [here](../../active-directory/managed-identities-azure-resources/overview.md#managed-identity-types).
2020

21-
Configuring a Fluid Relay resource with CMK can't be done through Azure portal yet.
21+
Configuring a Fluid Relay resource with CMK can't be done through Azure portal yet.
2222

23-
When you configure the Fluid Relay resource with CMK, the Azure Fluid Relay service configures the appropriate CMK encrypted settings on the Azure Storage account scope where your Fluid session artifacts are stored. For more information about CMK in Azure Storage, see [here](../../storage/common/customer-managed-keys-overview.md).
23+
When you configure the Fluid Relay resource with CMK, the Azure Fluid Relay service configures the appropriate CMK encrypted settings on the Azure Storage account scope where your Fluid session artifacts are stored. For more information about CMK in Azure Storage, see [here](../../storage/common/customer-managed-keys-overview.md).
2424

25-
To verify a Fluid Relay resource is using CMK, you can check the property of the resource by sending GET and see if it has valid, non-empty property of encryption.customerManagedKeyEncryption.
25+
To verify a Fluid Relay resource is using CMK, you can check the property of the resource by sending GET and see if it has valid, non-empty property of encryption.customerManagedKeyEncryption.
2626

27-
## Prerequisites:
27+
## Prerequisites
2828

29-
Before configuring CMK on your Azure Fluid Relay resource, the following prerequisites must be met:
29+
Before configuring CMK on your Azure Fluid Relay resource, the following prerequisites must be met:
3030
- Keys must be stored in an Azure Key Vault.
3131
- Keys must be RSA key and not EC key since EC key doesn’t support WRAP and UNWRAP.
32-
- A user assigned managed identity must be created with necessary permission (GET, WRAP and UNWRAP) to the key vault in step 1. More information [here](../../active-directory/managed-identities-azure-resources/tutorial-windows-vm-access-nonaad.md). Please grant GET, WRAP and UNWRAP under Key Permissions in AKV.
33-
- Azure Key Vault, user assigned identity, and the Fluid Relay resource must be in the same region and in the same Microsoft Entra tenant.
32+
- A user assigned managed identity must be created with necessary permission (GET, WRAP and UNWRAP) to the key vault in step 1. More information [here](../../active-directory/managed-identities-azure-resources/tutorial-windows-vm-access-nonaad.md). Grant GET, WRAP and UNWRAP under Key Permissions in AKV.
33+
- Azure Key Vault, user assigned identity, and the Fluid Relay resource must be in the same region and in the same Microsoft Entra tenant.
34+
- The Key Vault and the key must remain active for the entire lifetime of your Fluid Relay resources.
35+
- **Do NOT** delete or disable the key vault or the key until all associated Fluid Relay services are deleted.
36+
Otherwise, your Fluid Relay resource enters an **unusable state**. In this case, you need to [recover your key or key vault](/azure/key-vault/general/key-vault-recovery?tabs=azure-portal) first.
37+
- If you provide the key URL with a specific key version, **only that version** is used for CMK purposes.
38+
If you later add a new key version, you must **manually** update the key URL in the CMK settings of the Fluid Relay resource to make the new version effective.
39+
The Fluid Relay service fails if the specified key version is deleted or disabled without updating the resource to use a valid version.
40+
- To allow the Fluid Relay service to automatically use the latest key version of the key from your key vault, you can omit the key version in the encryption key URL. This setting makes Fluid Relay Service's storage dependency to check the key vault daily for a new version of the customer-managed key and automatically updates the key to the latest version.
41+
However, you are still responsible for managing and rotating key versions in your Key Vault.
42+
- Due to resource limitations, switching to this auto-update setting may fail. If that happens, specify a key version explicitly and perform a manual update on your Fluid Relay resource for new [key](/azure/key-vault/keys/about-keys) versions.
43+
3444

3545
## Create a Fluid Relay resource with CMK
3646

47+
### [REST API](#tab/rest)
3748
```
38-
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>"
49+
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>"
3950
```
4051

41-
Request payload format:
52+
Request payload format:
4253

4354
```
44-
{
45-
"location": "<the region you selected for Fluid Relay resource>",
46-
"identity": {
47-
"type": "UserAssigned",
48-
"userAssignedIdentities": {
49-
“<User assigned identity resource ID>": {}
50-
}
51-
},
52-
"properties": {
53-
"encryption": {
54-
"customerManagedKeyEncryption": {
55-
"keyEncryptionKeyIdentity": {
56-
"identityType": "UserAssigned",
57-
"userAssignedIdentityResourceId": "<User assigned identity resource ID>"
58-
},
59-
"keyEncryptionKeyUrl": "<key identifier>"
60-
}
61-
}
62-
}
63-
}
55+
{
56+
"location": "<the region you selected for Fluid Relay resource>",
57+
"identity": {
58+
"type": "UserAssigned",
59+
"userAssignedIdentities": {
60+
“<User assigned identity resource ID>": {}
61+
}
62+
},
63+
"properties": {
64+
"encryption": {
65+
"customerManagedKeyEncryption": {
66+
"keyEncryptionKeyIdentity": {
67+
"identityType": "UserAssigned",
68+
"userAssignedIdentityResourceId": "<User assigned identity resource ID>"
69+
},
70+
"keyEncryptionKeyUrl": "<key identifier>"
71+
}
72+
}
73+
}
74+
}
6475
```
6576

66-
Example userAssignedIdentities and userAssignedIdentityResourceId:
67-
/subscriptions/ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testUserAssignedIdentity
77+
Example userAssignedIdentities and userAssignedIdentityResourceId:
78+
/subscriptions/ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testUserAssignedIdentity
6879

6980
Example keyEncryptionKeyUrl: `https://test-key-vault.vault.azure.net/keys/testKey/testKeyVersionGuid`
7081

7182
Notes:
7283
- Identity.type must be UserAssigned. It is the identity type of the managed identity that is assigned to the Fluid Relay resource.
7384
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.identityType must be UserAssigned. It is the identity type of the managed identity that should be used for CMK.
74-
- Although you can specify more than one in Identity.userAssignedIdentities, only one user identity assigned to Fluid Relay resource specified will be used for CMK access the key vault for encryption.
85+
- Although you can specify more than one in Identity.userAssignedIdentities, only one user identity assigned to Fluid Relay resource specified is used for CMK access the key vault for encryption.
7586
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.userAssignedIdentityResourceId is the resource ID of the user assigned identity that should be used for CMK. Notice that it should be one of the identities in Identity.userAssignedIdentities (You must assign the identity to Fluid Relay resource before it can use it for CMK). Also, it should have necessary permissions on the key (provided by keyEncryptionKeyUrl).
76-
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyUrl is the key identifier used for CMK.
87+
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyUrl is the key identifier used for CMK.
88+
89+
### [PowerShell](#tab/azure-powershell)
90+
You need to install [Azure Fluid Relay module](/powershell/module/az.fluidrelay) first.
91+
92+
```azurepowershell
93+
Install-Module Az.FluidRelay
94+
```
95+
96+
And make sure you complete all the prerequisite steps.
97+
98+
Example of creating a Fluid Relay Service with CMK enabled:
99+
```azurepowershell
100+
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>"
101+
```
102+
103+
For more information about the command, see [New-AzFluidRelayServer](/powershell/module/az.fluidrelay/new-azfluidrelayserver)
104+
105+
**Notes:**
106+
107+
- The `KeyEncryptionKeyIdentityType` **must be** `UserAssigned` since `SystemAssigned` identity is not supported for CMK. It indicates the identity type to be used for Customer-Managed Key (CMK) encryption.
108+
- While multiple identities can be specified in the `UserAssignedIdentity` argument, **only** the identity defined in `KeyEncryptionKeyIdentityUserAssignedIdentityResourceId` is used to access the Key Vault for CMK encryption.
109+
- The `KeyEncryptionKeyIdentityUserAssignedIdentityResourceId` field should be set to the **resource ID** of the user-assigned identity intended for CMK access.
110+
- This identity must already be listed in the `UserAssignedIdentity` field.
111+
- Additionally, it needs the necessary permissions on the key specified in `CustomerManagedKeyEncryptionKeyUrl`.
112+
- `CustomerManagedKeyEncryptionKeyUrl` is the **key identifier** used for CMK.
113+
114+
### [Azure CLI](#tab/azure-cli)
115+
To create Fluid Relay with CMK enabled using Azure CLI, you need to install [fluid-relay](/cli/azure/fluid-relay) extension first. See [instructions](/cli/azure/azure-cli-extensions-overview).
77116

78-
## Update CMK settings of an existing Fluid Relay resource
117+
And make sure you complete all the [prerequisite](#prerequisites) steps.
79118

80-
You can update the following CMK settings on existing Fluid Relay resource:
119+
Example of creating a Fluid Relay Service with CMK enabled:
120+
```azurecli
121+
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>
122+
```
123+
124+
For more information about the command, see [az fluid-relay server create](/cli/azure/fluid-relay/server?view=azure-cli-latest#az-fluid-relay-server-create)
125+
126+
**Notes:**
127+
128+
- These arguments must be provided in **stringified JSON** format.
129+
- `identity`, `key-identity`
130+
- The `type` field under `identity` **must be** `UserAssigned`. It specifies the identity type of the managed identity assigned to the Fluid Relay resource.
131+
- The `identity-type` field under `key-identity` **must also be** `UserAssigned`. It indicates the identity type to be used for Customer-Managed Key (CMK) encryption.
132+
- While multiple identities can be specified in the `identity` argument, **only** the identity defined in `key-identity` is used to access the Key Vault for CMK encryption.
133+
- The `user-assigned-identities` field under `key-identity` should be set to the **resource ID** of the user-assigned identity intended for CMK access.
134+
- This identity must already be listed in the `identity` field.
135+
- Additionally, it needs the necessary permissions on the key specified in `key-url`.
136+
- `key-url` is the **key identifier** used for CMK.
137+
138+
---
139+
140+
## Update CMK settings of an existing Fluid Relay resource
141+
142+
You can update the following CMK settings on existing Fluid Relay resource:
81143
- Change the identity that is used for accessing the key encryption key.
82144
- Change the key encryption key identifier (key URL).
83-
- Change the key version of the key encryption key.
145+
- Change the key version of the key encryption key.
146+
147+
You cannot disable CMK on existing Fluid Relay resource once it is enabled.
148+
149+
Before updating the key encryption key (by identifier or version), ensure that **the previous key version is still enabled and has not expired in your key vault**. Otherwise, the update operation fails.
150+
151+
When using the update command, you may specify only the parameters that are changed—unchanged arguments can be omitted.
84152

85-
Note that you cannot disable CMK on existing Fluid Relay resource once it is enabled.
153+
All updates must satisfy the [prerequisites](#prerequisites) described in this page.
86154

87-
Request URL:
155+
### [REST API](#tab/rest)
156+
Request URL:
88157

89158
```
90-
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"
159+
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"
91160
```
92161

93162
Request payload example for updating key encryption key URL:
94163

95164
```
96-
{
97-
"properties": {
98-
"encryption": {
99-
"customerManagedKeyEncryption": {
100-
"keyEncryptionKeyUrl": "https://test_key_vault.vault.azure.net/keys/testKey /xxxxxxxxxxxxxxxx"
101-
}
102-
}
103-
}
165+
{
166+
"properties": {
167+
"encryption": {
168+
"customerManagedKeyEncryption": {
169+
"keyEncryptionKeyUrl": "https://test_key_vault.vault.azure.net/keys/testKey /xxxxxxxxxxxxxxxx"
170+
}
171+
}
172+
}
104173
}
105174
```
106175

176+
### [PowerShell](#tab/azure-powershell)
177+
You need to install [Azure Fluid Relay module](/powershell/module/az.fluidrelay) first.
178+
179+
```azurepowershell
180+
Install-Module Az.FluidRelay
181+
```
182+
183+
During an update, you only need to provide the parameters that need to be changed.
184+
185+
Update encryption key URL
186+
```azurepowershell
187+
Update-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -CustomerManagedKeyEncryptionKeyUrl "<new key URL>"
188+
```
189+
190+
Update assigned identity for CMK
191+
```azurepowershell
192+
Update-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -KeyEncryptionKeyIdentityUserAssignedIdentityResourceId "<new user assigned resource id>"
193+
```
194+
195+
For more information about the command, see [Update-AzFluidRelayServer](/powershell/module/az.fluidrelay/update-azfluidrelayserver)
196+
197+
### [Azure CLI](#tab/azure-cli)
198+
199+
Update encryption key URL
200+
```azurecli
201+
az fluid-relay server update --server-name <Fluid Relay Service name> --resource-group <resource group> --key-url <new key URL>
202+
```
203+
204+
Updating `identity` and `key-identity` follows the same format as when creating the resource. However, during an update, you only need to provide the parameters that need to be changed.
205+
206+
Update assigned identity for CMK
207+
```azurecli
208+
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>"}'
209+
```
210+
211+
For more information about the command, see [az fluid-relay server update](/cli/azure/fluid-relay/server?view=azure-cli-latest#az-fluid-relay-server-update)
212+
213+
---
214+
215+
## Troubleshooting
216+
217+
### Error: Unexpected error happened when configuring CMK
218+
- Ensure your configuration meets **all the requirements** listed in the [prerequisites](#prerequisites) section.
219+
220+
- Check if you have firewall rules enabled in your Azure Key Vault. If so, turn on "Allow trusted Microsoft services to bypass this firewall" option. See [Key Vault firewall-enabled trusted services only](/azure/key-vault/general/network-security?WT.mc_id=Portal-Microsoft_Azure_KeyVault#key-vault-firewall-enabled-trusted-services-only)
221+
222+
- For existing Fluid Relay resources, verify that the key—**or the specific key version**, if one is specified in the CMK settings—is still **enabled** and **not expired** in your Key Vault.
223+
107224
## See also
108225

109226
- [Overview of Azure Fluid Relay architecture](architecture.md)

0 commit comments

Comments
 (0)