You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/service-bus-messaging/configure-customer-managed-key.md
+48-47Lines changed: 48 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,19 +2,19 @@
2
2
title: Configure your own key for encrypting Azure Service Bus data at rest
3
3
description: This article provides information on how to configure your own key for encrypting Azure Service Bus data rest.
4
4
ms.topic: conceptual
5
-
ms.date: 05/13/2024
5
+
ms.date: 02/03/2025
6
6
---
7
7
8
8
# Configure customer-managed keys for encrypting Azure Service Bus data at rest
9
-
Azure Service Bus Premium provides encryption of data at rest with Azure Storage Service Encryption (Azure SSE). Service Bus Premium uses Azure Storage to store the data. All the data that's stored with Azure Storage is encrypted using Microsoft-managed keys. If you use your own key (also referred to as Bring Your Own Key (BYOK) or customer-managed key), the data is still encrypted using the Microsoft-managed key, but in addition the Microsoft-managed key is encrypted using the customer-managed key. This feature enables you to create, rotate, disable, and revoke access to customer-managed keys that are used for encrypting Microsoft-managed keys. Enabling the BYOK feature is a one time setup process on your namespace.
9
+
Azure Service Bus Premium provides encryption of data at rest with Azure Storage Service Encryption (Azure SSE). Service Bus Premium uses Azure Storage to store the data. All the data that's stored in Azure Storage is encrypted using Microsoft-managed keys. If you use your own key (also referred to as Bring Your Own Key (BYOK) or customer-managed key), the data is still encrypted using the Microsoft-managed key, but in addition the Microsoft-managed key is encrypted using the customer-managed key. This feature enables you to create, rotate, disable, and revoke access to customer-managed keys that are used for encrypting Microsoft-managed keys. Enabling the BYOK feature is a one time setup process on your namespace.
10
10
11
11
There are some caveats to the customer managed key for service side encryption.
12
12
- This feature is supported by [Azure Service Bus Premium](service-bus-premium-messaging.md) tier. It can't be enabled for standard tier Service Bus namespaces.
13
13
- The encryption can only be enabled for new or empty namespaces. If the namespace contains any queues or topics, then the encryption operation fails.
14
14
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?](/azure/key-vault/general/overview)
15
+
You can use Azure Key Vault (including Azure Key Vault Managed Hardware Security Module (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?](/azure/key-vault/general/overview)
16
16
17
-
If you only need to encrypt certain properties of your messages, consider using a library like [NServiceBus](https://docs.particular.net/nservicebus/security/property-encryption) for that.
17
+
If you only need to encrypt certain properties of your messages, consider using a library like [NServiceBus](https://docs.particular.net/nservicebus/security/property-encryption).
18
18
19
19
## Enable customer-managed keys (Azure portal)
20
20
@@ -33,83 +33,84 @@ To enable customer-managed keys in the Azure portal, follow these steps:
33
33
34
34
After you enable customer-managed keys, you need to associate the customer managed key with your Azure Service Bus namespace. Service Bus 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](/azure/key-vault/general/key-vault-recovery) or [CLI](/azure/key-vault/general/key-vault-recovery).
35
35
36
-
1. To create a new key vault, follow the Azure Key Vault [Quickstart](/azure/key-vault/general/overview). For more information about importing existing keys, see [About keys, secrets, and certificates](/azure/key-vault/general/about-keys-secrets-certificates).
36
+
### Create key vault or keyvault managed HSM
37
37
38
-
> [!IMPORTANT]
39
-
> Using customer-managed keys with Azure Service Bus requires that the key vault have two required properties configured. They are: **Soft Delete** and **Do Not Purge**. The Soft Delete property is enabled by default when you create a new key vault in the Azure portal whereas the Purge Protection is optional so make sure to select it when creating the Key Vault. Also, if you need to enable these properties on an existing key vault, you must use either PowerShell or Azure CLI.
38
+
> [!IMPORTANT]
39
+
> Using customer-managed keys with Azure Service Bus requires that the vault have two required properties configured. They are: **Soft Delete** and **Do Not Purge**. The Soft Delete property is enabled by default when you create a new vault in the Azure portal whereas the Purge Protection is optional so make sure to select it when creating the vault. Also, if you need to enable these properties on an existing key vault, you must use either PowerShell or Azure CLI.
40
40
41
41
# [Key Vault](#tab/Key-Vault)
42
+
43
+
- To create a new Key Vault, follow the Azure Key Vault [Quickstart](/azure/key-vault/general/quick-create-cli). For information about Azure KeyVault, see [About Azure KeyVault](/azure/key-vault/general/overview).
44
+
- 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
45
43
-
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.
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.
- 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.
50
50
51
-
```azurecli-interactive
52
-
az keyvault update --name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true
53
-
```
51
+
```azurecli-interactive
52
+
az keyvault update --name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true
- To create a new Managed HSM, follow the Managed HSM [Quickstart](/azure/key-vault/managed-hsm/quick-create-cli). For information about Azure KeyVault, see [About Azure KeyVault](/azure/key-vault/general/overview).
58
+
- 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.
56
59
57
-
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.
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.
64
+
After creation, you need to [activate the Managed HSM](/azure/key-vault/managed-hsm/quick-create-cli#activate-your-managed-hsm) and ensure that you have the correct permissions to generate keys by [assigning an RBAC role and local RBAC role](/azure/key-vault/managed-hsm/secure-your-managed-hsm) with the correct permissions.
65
+
- 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.
64
66
65
-
```azurecli-interactive
66
-
az keyvault update --hsm-name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true
67
-
```
67
+
```azurecli-interactive
68
+
az keyvault update --hsm-name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true
69
+
```
70
+
68
71
---
69
72
73
+
## Create keys
70
74
Create keys by following these steps:
71
75
72
76
1. To create a new key, select **Generate/Import** from the **Keys** menu under **Settings**.
73
77
74
-
75
-
78
+
76
79
1. Set **Options** to **Generate** and give the key a name.
77
80
78
-
79
-
81
+
80
82
1. You can now select this key to associate with the Service Bus namespace for encrypting from the drop-down list.
81
83
82
84
83
85
84
86
> [!NOTE]
85
-
> For redundancy, you can add up to 3 keys. In the event that one of the keys has expired, or is not accessible, the other keys will be used for encryption.
86
-
87
-
1. Fill in the details for the key and click **Select**. This enables the encryption of the Microsoft-managed key with your key (customer-managed key).
87
+
> For redundancy, you can add up to three keys. If one of the keys is expired, or isn't accessible, the other keys are used for encryption.
88
+
1. Fill in the details for the key and click **Select**. It enables the encryption of the Microsoft-managed key with your key (customer-managed key).
88
89
89
90
> [!IMPORTANT]
90
-
> If you are looking to use Customer managed key along with [Geo-Disaster Recovery](service-bus-geo-dr.md), please review this section.
91
+
> If you're looking to use Customer managed key along with [Geo-Disaster Recovery](service-bus-geo-dr.md), review this section.
91
92
>
92
93
> To enable encryption of Microsoft-managed key with a customer managed key, an [access policy](/azure/key-vault/general/security-features) is set up for the Service Bus' managed identity on the specified Azure KeyVault. This ensures controlled access to the Azure KeyVault from the Azure Service Bus namespace.
93
94
>
94
-
> Due to this:
95
+
> Due to this behavior:
95
96
>
96
-
> * If [Geo-Disaster Recovery](service-bus-geo-dr.md) is already enabled for the Service Bus namespace and you are looking to enable customer managed key, then
97
+
> * If [Geo-Disaster Recovery](service-bus-geo-dr.md) is already enabled for the Service Bus namespace and you're looking to enable customer managed key, then
97
98
> * Break the pairing
98
99
> * [Set up the access policy](/azure/key-vault/general/assign-access-policy-portal) for the managed identity for both the primary and secondary namespaces to the key vault.
99
100
> * Set up encryption on the primary namespace.
100
101
> * Re-pair the primary and secondary namespaces.
101
102
>
102
-
> * If you are looking to enable Geo-Disaster Recovery on a Service Bus namespace where customer managed key is already set up, then -
103
+
> * If you're looking to enable Geo-Disaster Recovery on a Service Bus namespace where customer managed key is already set up, then -
103
104
> * [Set up the access policy](/azure/key-vault/general/assign-access-policy-portal) for the managed identity for the secondary namespace to the key vault.
104
105
> * Pair the primary and secondary namespaces.
105
106
>
106
-
> * Once paired, the secondary namespace will use the key vault configured for the primary namespace. If the key vault for both namespaces is different before Geo-Disaster Recovery pairing, the user must delegate an access policy or RBAC role for the managed identity of the secondary namespace in the key vault associated with primary namespace.
107
+
> * Once paired, the secondary namespace uses the key vault configured for the primary namespace. If the key vault for both namespaces is different before Geo-Disaster Recovery pairing, the user must delegate an access policy or RBAC role for the managed identity of the secondary namespace in the key vault associated with primary namespace.
107
108
108
109
## Managed identities
109
110
There are two types of managed identities that you can assign to a Service Bus namespace.
110
111
111
112
- **System-assigned**: You can enable a managed identity directly on a Service Bus namespace. When you enable a system-assigned managed identity, an identity is created in Microsoft Entra that's tied to the lifecycle of that Service Bus namespace. So when the namespace is deleted, Azure automatically deletes the identity for you. By design, only that Azure resource (namespace) can use this identity to request tokens from Microsoft Entra ID.
112
-
-**User-assigned**: You may also create a managed identity as a standalone Azure resource, which is called user-assigned identity. You can create a user-assigned managed identity and assign it to one or more Service Bus namespaces. When you use user-assigned managed identities, the identity is managed separately from the resources that use it. They aren't tied to the lifecycle of the namespace. You can explicitly delete a user-assigned identity when you no longer need it.
113
+
- **User-assigned**: You can also create a managed identity as a standalone Azure resource, which is called user-assigned identity. You can create a user-assigned managed identity and assign it to one or more Service Bus namespaces. When you use user-assigned managed identities, the identity is managed separately from the resources that use it. They aren't tied to the lifecycle of the namespace. You can explicitly delete a user-assigned identity when you no longer need it.
113
114
114
115
For more information, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md).
### Encrypt data in Service Bus namespace with customer-managed key from key vault
216
217
217
-
You have done the following steps so far:
218
+
You did the following steps so far:
218
219
219
220
1. Created a premium namespace with a managed identity.
220
221
1. Create a key vault and granted the managed identity access to the key vault.
@@ -613,9 +614,9 @@ See the following example for using the user-managed identity for the encryption
613
614
614
615
If you require a higher level of assurance that your data is secure, you can enable infrastructure level encryption, which is also known as Double Encryption.
615
616
616
-
When infrastructure encryption is enabled, data in the Azure Service Bus is encrypted twice, once at the service level and once at the infrastructure level, using two different encryption algorithms and two different keys. Hence, infrastructure encryption of Azure Service Bus data protects against a scenario where one of the encryption algorithms or keys may be compromised.
617
+
When infrastructure encryption is enabled, data in the Azure Service Bus is encrypted twice, once at the service level and once at the infrastructure level, using two different encryption algorithms and two different keys. Hence, infrastructure encryption of Azure Service Bus data protects against a scenario where one of the encryption algorithms or keys can be compromised.
617
618
618
-
You can enable infrastructure encryption by updating the Azure Resource Manager template with `requireInfrastructureEncryption` property in the above **UpdateServiceBusNamespaceWithEncryption.json** as shown below.
619
+
You can enable infrastructure encryption by updating the Azure Resource Manager template with `requireInfrastructureEncryption` property in the **UpdateServiceBusNamespaceWithEncryption.json** as shown in the following example.
619
620
620
621
```json
621
622
"properties":{
@@ -645,14 +646,14 @@ Revoking access to the encryption keys won't purge the data from Service Bus. Ho
645
646
Once the encryption key is revoked, the Service Bus service on the encrypted namespace becomes inoperable. If the access to the key is enabled or the deleted key is restored, Service Bus service picks the key so you can access the data from the encrypted Service Bus namespace.
646
647
647
648
### Caching of keys
648
-
The Service Bus instance polls its listed encryption keys every 5 minutes. It caches and uses them until the next poll, which is after 5 minutes. As long as at least one key is available, queues and topics are accessible. If all listed keys are inaccessible when it polls, all queues and topics become unavailable.
649
+
The Service Bus instance polls its listed encryption keys every 5 minutes. It caches and uses them until the next poll, which is after 5 minutes. As long as at least one key is available, queues, and topics are accessible. If all listed keys are inaccessible when it polls, all queues and topics become unavailable.
649
650
650
651
Here are more details:
651
652
652
653
- Every 5 minutes, the Service Bus service polls all customer-managed keys listed in the namespace’s record:
653
-
- If a key has been rotated, the record is updated with the new key.
654
-
- If a key has been revoked, the key is removed from the record.
655
-
- If all keys have been revoked, the namespace’s encryption status is set to **Revoked**. The data can't be accessed from the Service Bus namespace.
654
+
- If a key was rotated, the record is updated with the new key.
655
+
- If a key was revoked, the key is removed from the record.
656
+
- If all keys were revoked, the namespace’s encryption status is set to **Revoked**. The data can't be accessed from the Service Bus namespace.
656
657
657
658
## Considerations when using Geo-Disaster Recovery
658
659
@@ -689,7 +690,7 @@ You get an error stating that the Service Bus namespace is disabled because the
689
690
690
691
### Cause
691
692
692
-
You may be using the `resource_id` or `version`, which links to a specific version of the key, which may have expired. If a specific version is provided, Service Bus uses that version of the key, even if the key is rotated.
693
+
You're be using the `resource_id` or `version`, which links to a specific version of the key, which is expired. If a specific version is provided, Service Bus uses that version of the key, even if the key is rotated.
![prmerger-automator[bot]](https://avatars.githubusercontent.com/u/22479449?v=4&size=40){kind=avatar}
0 commit comments