Skip to content

Commit 21fc275

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #275207 from EldertGrootenboer/managed-hsm-cmk
Added Managed HSM to CMK docs
2 parents 13453f9 + bfdae1e commit 21fc275

File tree

2 files changed

+322
-223
lines changed

2 files changed

+322
-223
lines changed

‎articles/event-hubs/configure-customer-managed-key.md

Lines changed: 148 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Configure your own key for encrypting Azure Event Hubs data at rest
33
description: This article provides information on how to configure your own key for encrypting Azure Event Hubs data rest.
44
ms.topic: conceptual
5-
ms.date: 08/18/2021
5+
ms.date: 05/13/2024
66
---
77

88
# Configure customer-managed keys for encrypting Azure Event Hubs data at rest
@@ -12,7 +12,7 @@ Azure Event Hubs provides encryption of data at rest with Azure Storage Service
1212
> - The BYOK capability is supported by **premium** and **dedicated** tiers of Event Hubs.
1313
> - The encryption can be enabled only for new or empty namespaces. If the namespace contains event hubs, the encryption operation will fail.
1414
15-
You can use Azure Key Vault to manage your keys and audit your key usage. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. For more information about Azure Key Vault, see [What is Azure Key Vault?](../key-vault/general/overview.md)
15+
You can use Azure Key Vault (including Azure Key Vault Managed HSM) to manage your keys and audit your key usage. You can either create your own keys and store them in a key vault, or you can use the Azure Key Vault APIs to generate keys. For more information about Azure Key Vault, see [What is Azure Key Vault?](../key-vault/general/overview.md)
1616

1717
This article shows how to configure a key vault with customer-managed keys by using the Azure portal. To learn how to create a key vault using the Azure portal, see [Quickstart: Create an Azure Key Vault using the Azure portal](../key-vault/general/quick-create-portal.md).
1818

@@ -25,24 +25,45 @@ To enable customer-managed keys in the Azure portal, follow these steps. If you
2525

2626
![Enable customer managed key](./media/configure-customer-managed-key/enable-customer-managed-key.png)
2727

28+
> [!NOTE]
29+
> Currently you can't configure Azure Key Vault Managed HSM through the portal.
30+
2831
## Set up a key vault with keys
2932
After you enable customer-managed keys, you need to associate the customer managed key with your Azure Event Hubs namespace. Event Hubs supports only Azure Key Vault. If you enable the **Encryption with customer-managed key** option in the previous section, you need to have the key imported into Azure Key Vault. Also, the keys must have **Soft Delete** and **Do Not Purge** configured for the key. These settings can be configured using [PowerShell](../key-vault/general/key-vault-recovery.md) or [CLI](../key-vault/general/key-vault-recovery.md).
3033

3134
1. To create a new key vault, follow the Azure Key Vault [Quickstart](../key-vault/general/overview.md). For more information about importing existing keys, see [About keys, secrets, and certificates](../key-vault/general/about-keys-secrets-certificates.md).
3235

3336
> [!IMPORTANT]
3437
> Using customer-managed keys with Azure Event Hubs requires that the key vault have two required properties configured. They are: **Soft Delete** and **Do Not Purge**. These properties are enabled by default when you create a new key vault in the Azure portal. However, if you need to enable these properties on an existing key vault, you must use either PowerShell or Azure CLI.
35-
1. To turn on both soft delete and purge protection when creating a vault, use the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
3638
37-
```azurecli-interactive
38-
az keyvault create --name ContosoVault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true
39-
```
40-
1. To add purge protection to an existing vault (that already has soft delete enabled), use the [az keyvault update](/cli/azure/keyvault#az-keyvault-update) command.
39+
# [Key Vault](#tab/Key-Vault)
4140

42-
```azurecli-interactive
43-
az keyvault update --name ContosoVault --resource-group ContosoRG --enable-purge-protection true
44-
```
45-
1. Create keys by following these steps:
41+
2. To turn on both soft delete and purge protection when creating a vault, use the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
42+
43+
```azurecli-interactive
44+
az keyvault create --name ContosoVault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true
45+
```
46+
3. To add purge protection to an existing vault (that already has soft delete enabled), use the [az keyvault update](/cli/azure/keyvault#az-keyvault-update) command.
47+
48+
```azurecli-interactive
49+
az keyvault update --name ContosoVault --resource-group ContosoRG --enable-purge-protection true
50+
```
51+
52+
# [Key Vault Managed HSM](#tab/Key-Vault-Managed-HSM)
53+
54+
2. To turn on both soft delete and purge protection when creating a vault, use the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
55+
56+
```azurecli-interactive
57+
az keyvault create --hsm-name ContosoVault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true
58+
```
59+
3. To add purge protection to an existing vault (that already has soft delete enabled), use the [az keyvault update](/cli/azure/keyvault#az-keyvault-update) command.
60+
61+
```azurecli-interactive
62+
az keyvault update --hsm-name ContosoVault --resource-group ContosoRG --enable-purge-protection true
63+
```
64+
---
65+
66+
4. Create keys by following these steps:
4667
1. To create a new key, select **Generate/Import** from the **Keys** menu under **Settings**.
4768

4869
![Select Generate/Import button](./media/configure-customer-managed-key/select-generate-import.png)
@@ -65,15 +86,13 @@ There are two types of managed identities that you can assign to an Event Hubs n
6586

6687
For more information, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md).
6788

68-
6989
## Encrypt using system-assigned identities (template)
7090
This section shows how to do the following tasks using **Azure Resource Manager templates**.
7191

7292
1. Create an **Event Hubs namespace** with a managed service identity.
7393
2. Create a **key vault** and grant the service identity access to the key vault.
7494
3. Update the Event Hubs namespace with the key vault information (key/value).
7595

76-
7796
### Create an Event Hubs cluster and namespace with managed service identity
7897
This section shows you how to create an Azure Event Hubs namespace with managed service identity by using an Azure Resource Manager template and PowerShell.
7998

@@ -182,26 +201,13 @@ This section shows you how to create an Azure Event Hubs namespace with managed
182201

183202
### Grant Event Hubs namespace identity access to key vault
184203

185-
1. Run the following command to create a key vault with **purge protection** and **soft-delete** enabled.
204+
Set the key vault access policy so that the managed identity of the Event Hubs namespace can access key value in the key vault. Use the ID of the Event Hubs namespace from the previous section.
186205

187-
```powershell
188-
New-AzureRmKeyVault -Name {keyVaultName} -ResourceGroupName {RGName} -Location {location} -EnableSoftDelete -EnablePurgeProtection
189-
```
190-
191-
(OR)
192-
193-
Run the following command to update an **existing key vault**. Specify values for resource group and key vault names before running the command.
194-
195-
```powershell
196-
($updatedKeyVault = Get-AzureRmResource -ResourceId (Get-AzureRmKeyVault -ResourceGroupName {RGName} -VaultName {keyVaultName}).ResourceId).Properties| Add-Member -MemberType "NoteProperty" -Name "enableSoftDelete" -Value "true"-Force | Add-Member -MemberType "NoteProperty" -Name "enablePurgeProtection" -Value "true" -Force
197-
```
198-
2. Set the key vault access policy so that the managed identity of the Event Hubs namespace can access key value in the key vault. Use the ID of the Event Hubs namespace from the previous section.
206+
```powershell
207+
$identity = (Get-AzureRmResource -ResourceId $EventHubNamespaceId -ExpandProperties).Identity
199208

200-
```powershell
201-
$identity = (Get-AzureRmResource -ResourceId $EventHubNamespaceId -ExpandProperties).Identity
202-
203-
Set-AzureRmKeyVaultAccessPolicy -VaultName {keyVaultName} -ResourceGroupName {RGName} -ObjectId $identity.PrincipalId -PermissionsToKeys get,wrapKey,unwrapKey,list
204-
```
209+
Set-AzureRmKeyVaultAccessPolicy -VaultName {keyVaultName} -ResourceGroupName {RGName} -ObjectId $identity.PrincipalId -PermissionsToKeys get,wrapKey,unwrapKey,list
210+
```
205211

206212
### Encrypt data in Event Hubs namespace with customer-managed key from key vault
207213
You have done the following steps so far:
@@ -293,29 +299,56 @@ In this step, you will update the Event Hubs namespace with key vault informatio
293299
> - `<KeyVaultName>` - Name of your key vault
294300
> - `<KeyName>` - Name of the key in the key vault
295301

296-
```json
297-
{
298-
"$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
299-
"contentVersion":"1.0.0.0",
300-
"parameters":{
301-
"clusterName":{
302-
"value":"<EventHubsClusterName>"
303-
},
304-
"namespaceName":{
305-
"value":"<EventHubsNamespaceName>"
306-
},
307-
"location":{
308-
"value":"<Location>"
309-
},
310-
"keyName":{
311-
"value":"<KeyName>"
312-
},
313-
"keyVaultUri":{
314-
"value":"https://<KeyVaultName>.vault.azure.net"
315-
}
316-
}
317-
}
318-
```
302+
# [Key Vault](#tab/Key-Vault)
303+
304+
```json
305+
{
306+
"$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
307+
"contentVersion":"1.0.0.0",
308+
"parameters":{
309+
"clusterName":{
310+
"value":"<EventHubsClusterName>"
311+
},
312+
"namespaceName":{
313+
"value":"<EventHubsNamespaceName>"
314+
},
315+
"location":{
316+
"value":"<Location>"
317+
},
318+
"keyName":{
319+
"value":"<KeyName>"
320+
},
321+
"keyVaultUri":{
322+
"value":"https://<KeyVaultName>.vault.azure.net"
323+
}
324+
}
325+
}
326+
```
327+
328+
# [Key Vault Managed HSM](#tab/Key-Vault-Managed-HSM)
329+
330+
```json
331+
{
332+
"$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
333+
"contentVersion":"1.0.0.0",
334+
"parameters":{
335+
"namespaceName":{
336+
"value":"<ServiceBusNamespaceName>"
337+
},
338+
"location":{
339+
"value":"<Location>"
340+
},
341+
"keyName":{
342+
"value":"<KeyName>"
343+
},
344+
"keyVaultUri":{
345+
"value":"https://<KeyVaultName>.managedhsm.azure.net"
346+
}
347+
}
348+
}
349+
```
350+
---
351+
319352
3. Run the following PowerShell command to deploy the Resource Manager template. Replace `{MyRG}` with the name of your resource group before running the command.
320353

321354
```powershell
@@ -334,27 +367,14 @@ Follow instructions from the [Create a user-assigned managed identity](../active
334367
> [!NOTE]
335368
> You can assign up to **4** user identities to a namespace. These associations are deleted when the namespace is deleted or when you pass the `identity -> type` in the template to `None`.
336369
337-
### Create a key vault and grant access to user-assigned identity
370+
### Grant access to user-assigned identity
338371
339-
1. Run the following command to create a key vault with purge protection and soft-delete enabled.
340-
341-
```azurepowershell-interactive
342-
New-AzureRmKeyVault -Name "{keyVaultName}" -ResourceGroupName {RGName} -Location "{location}" -EnableSoftDelete -EnablePurgeProtection
343-
```
344-
345-
(OR)
346-
347-
Run the following command to update an existing key vault. Specify values for resource group and key vault names before running the command.
348-
349-
```azurepowershell-interactive
350-
($updatedKeyVault = Get-AzureRmResource -ResourceId (Get-AzureRmKeyVault -ResourceGroupName {RGName} -VaultName {keyVaultName}).ResourceId).Properties| Add-Member -MemberType "NoteProperty" -Name "enableSoftDelete" -Value "true"-Force | Add-Member -MemberType "NoteProperty" -Name "enablePurgeProtection" -Value "true" -Force
351-
```
352-
2. Get the **Service principal ID** for the user identity using the following PowerShell command. In the example, `ud1` is the user-assigned identity to be used for encryption.
372+
1. Get the **Service principal ID** for the user identity using the following PowerShell command. In the example, `ud1` is the user-assigned identity to be used for encryption.
353373
354374
```azurepowershell-interactive
355375
$servicePrincipal=Get-AzADServicePrincipal -SearchString "ud1"
356376
```
357-
3. Grant the user-assigned identity access to the key vault by assigning an access policy.
377+
1. Grant the user-assigned identity access to the key vault by assigning an access policy.
358378
359379
```azurepowershell-interactive
360380
Set-AzureRmKeyVaultAccessPolicy -VaultName {keyVaultName} -ResourceGroupName {RGName} -ObjectId $servicePrincipal.Id -PermissionsToKeys get,wrapKey,unwrapKey,list
@@ -366,7 +386,7 @@ Follow instructions from the [Create a user-assigned managed identity](../active
366386
### Create an Event Hubs namespace with user identity and key vault information
367387
This section gives you an example that shows you how to do the following tasks using an Azure Resource Manager template.
368388
369-
- Assign a user-managed identity to an Event Hubs namespace.
389+
1. Assign a user-managed identity to an Event Hubs namespace.
370390
371391
```json
372392
"identity": {
@@ -376,7 +396,7 @@ This section gives you an example that shows you how to do the following tasks u
376396
}
377397
},
378398
```
379-
- Enable encryption on the namespace by specifying a key from your key vault and the user-managed identity to access the key.
399+
1. Enable encryption on the namespace by specifying a key from your key vault and the user-managed identity to access the key.
380400
381401
```json
382402
"encryption":{
@@ -393,7 +413,6 @@ This section gives you an example that shows you how to do the following tasks u
393413
}
394414
```
395415
396-
397416
1. Create a JSON file named **CreateEventHubsNamespaceWithUserIdentityAndEncryption.json** with the following content:
398417
399418
```json
@@ -488,31 +507,62 @@ This section gives you an example that shows you how to do the following tasks u
488507
```
489508
1. Create a template parameter file: **CreateEventHubsNamespaceWithUserIdentityAndEncryptionParams.json**.
490509
491-
```json
492-
{
493-
"$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
494-
"contentVersion":"1.0.0.0",
495-
"parameters":{
496-
"namespaceName":{
497-
"value":"<EventHubsNamespaceName>"
498-
},
499-
"location":{
500-
"value":"<Location>"
501-
},
502-
"keyVaultUri":{
503-
"value":"https://<KeyVaultName>.vault.azure.net"
504-
},
505-
"keyName":{
506-
"value":"<KeyName>"
507-
},
508-
"identity": {
509-
"value": {
510-
"userAssignedIdentity": "/subscriptions/<AZURE SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP NAME>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER MANAGED IDENTITY NAME>"
511-
}
510+
# [Key Vault](#tab/Key-Vault)
511+
512+
```json
513+
{
514+
"$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
515+
"contentVersion":"1.0.0.0",
516+
"parameters":{
517+
"namespaceName":{
518+
"value":"<EventHubsNamespaceName>"
519+
},
520+
"location":{
521+
"value":"<Location>"
522+
},
523+
"keyVaultUri":{
524+
"value":"https://<KeyVaultName>.vault.azure.net"
525+
},
526+
"keyName":{
527+
"value":"<KeyName>"
528+
},
529+
"identity": {
530+
"value": {
531+
"userAssignedIdentity": "/subscriptions/<AZURE SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP NAME>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER MANAGED IDENTITY NAME>"
512532
}
513-
}
514-
}
515-
```
533+
}
534+
}
535+
}
536+
```
537+
538+
# [Key Vault Managed HSM](#tab/Key-Vault-Managed-HSM)
539+
540+
```json
541+
{
542+
"$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
543+
"contentVersion":"1.0.0.0",
544+
"parameters":{
545+
"namespaceName":{
546+
"value":"<ServiceBusNamespaceName>"
547+
},
548+
"location":{
549+
"value":"<Location>"
550+
},
551+
"keyVaultUri":{
552+
"value":"https://<KeyVaultName>.managedhsm.azure.net"
553+
},
554+
"keyName":{
555+
"value":"<KeyName>"
556+
},
557+
"identity": {
558+
"value": {
559+
"userAssignedIdentity": "/subscriptions/<AZURE SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP NAME>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER MANAGED IDENTITY NAME>"
560+
}
561+
}
562+
}
563+
}
564+
```
565+
---
516566

517567
In the parameter file, replace placeholders with appropriate values.
518568

@@ -526,13 +576,12 @@ This section gives you an example that shows you how to do the following tasks u
526576
| `<RESOURCE GROUP NAME>` | Resource group of the user-managed identity. |
527577
| `<USER MANAGED IDENTITY NAME>` | Name of the user-managed identity. |
528578

529-
3. Run the following PowerShell command to deploy the Resource Manager template. Replace `{MyRG}` with the name of your resource group before running the command.
579+
1. Run the following PowerShell command to deploy the Resource Manager template. Replace `{MyRG}` with the name of your resource group before running the command.
530580

531581
```azurepowershell-interactive
532582
New-AzResourceGroupDeployment -Name CreateEventHubsNamespaceWithEncryption -ResourceGroupName {MyRG} -TemplateFile ./ CreateEventHubsNamespaceWithUserIdentityAndEncryption.json -TemplateParameterFile ./ CreateEventHubsNamespaceWithUserIdentityAndEncryptionParams.json
533583
```
534584
535-
536585
## Use both user-assigned and system-assigned identities
537586
A namespace can have both system-assigned and user-assigned identities at the same time. In this case, the `type` property would be `SystemAssigned`, `UserAssigned` as shown in the following example.
538587

0 commit comments

Comments
 (0)