Added Managed HSM support with CMK for SB

EldertGrootenboerMS · EldertGrootenboerMS · commit 6d102b53d78d · 2024-05-13T09:10:42.000-07:00
diff --git a/articles/service-bus-messaging/configure-customer-managed-key.md b/articles/service-bus-messaging/configure-customer-managed-key.md
@@ -2,7 +2,7 @@
 title: Configure your own key for encrypting Azure Service Bus data at rest
 description: This article provides information on how to configure your own key for encrypting Azure Service Bus data rest. 
 ms.topic: conceptual
-ms.date: 06/26/2023
+ms.date: 05/13/2024
 ---
 
 # Configure customer-managed keys for encrypting Azure Service Bus data at rest
@@ -12,7 +12,7 @@ There are some caveats to the customer managed key for service side encryption.
 - 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.
 - The encryption can only be enabled for new or empty namespaces. If the namespace contains any queues or topics, then the encryption operation fails.
 
-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)
+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)
 
 ## Enable customer-managed keys (Azure portal)
 To enable customer-managed keys in the Azure portal, follow these steps:
@@ -23,6 +23,8 @@ To enable customer-managed keys in the Azure portal, follow these steps:
 
     ![Enable customer managed key](./media/configure-customer-managed-key/enable-customer-managed-key.png)
 
+> [!NOTE]
+> Currently you can't configure Azure Key Vault Managed HSM through the portal. 
 
 ## Set up a key vault with keys
 
@@ -32,6 +34,9 @@ After you enable customer-managed keys, you need to associate the customer manag
 
     > [!IMPORTANT]
     > 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.
+
+# [Key Vault](#tab/Key-Vault)
+
 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.
 
     ```azurecli-interactive
@@ -42,6 +47,22 @@ After you enable customer-managed keys, you need to associate the customer manag
     ```azurecli-interactive
     az keyvault update --name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true
     ```
+
+# [Key Vault Managed HSM](#tab/Key-Vault-Managed-HSM)
+
+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.
+
+    ```azurecli-interactive
+    az keyvault create --hsm-name contoso-SB-BYOK-keyvault --resource-group ContosoRG --location westus --enable-soft-delete true --enable-purge-protection true
+    ```    
+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.
+
+    ```azurecli-interactive
+    az keyvault update --hsm-name contoso-SB-BYOK-keyvault --resource-group ContosoRG --enable-purge-protection true
+    ```
+
+---
+
 1. Create keys by following these steps:
     1. To create a new key, select **Generate/Import** from the **Keys** menu under **Settings**.
         
@@ -61,23 +82,23 @@ After you enable customer-managed keys, you need to associate the customer manag
 
 
     > [!IMPORTANT]
-    > If you are looking to use Customer managed key along with Geo disaster recovery, please review this section. 
+    > If you are looking to use Customer managed key along with [Geo-Disaster Recovery](service-bus-geo-dr.md), please review this section. 
     >
     > To enable encryption of Microsoft-managed key with a customer managed key, an [access policy](../key-vault/general/security-features.md) 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.
     >
     > Due to this:
     > 
-    >   * 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 
+    >   * 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 
     >     * Break the pairing
     >     * [Set up the access policy](../key-vault/general/assign-access-policy-portal.md) for the managed identity for both the primary and secondary namespaces to the key vault.
     >     * Set up encryption on the primary namespace.
     >     * Re-pair the primary and secondary namespaces.
     > 
-    >   * If you are looking to enable Geo-DR on a Service Bus namespace where customer managed key is already set up, then -
+    >   * If you are looking to enable Geo-Disaster Recovery on a Service Bus namespace where customer managed key is already set up, then -
     >     * [Set up the access policy](../key-vault/general/assign-access-policy-portal.md) for the managed identity for the secondary namespace to the key vault.
     >     * Pair the primary and secondary namespaces.
     >    
-    >   * 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-DR 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.
+    >   * 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.
 
 ## Managed identities
 There are two types of managed identities that you can assign to a Service Bus namespace.
@@ -92,7 +113,7 @@ This section shows how to do the following tasks:
 
 1. Create a **premium** Service Bus namespace with a **managed service identity**.
 2. Create a **key vault** and grant the service identity access to the key vault. 
-3. Update the Service Bus namespace with the key vault information  (key/value). 
+3. Update the Service Bus namespace with the key vault information (key/value). 
 
 ### Create a premium Service Bus namespace with managed service identity
 This section shows you how to create an Azure Service Bus namespace with managed service identity by using an Azure Resource Manager template and PowerShell. 
@@ -145,7 +166,7 @@ This section shows you how to create an Azure Service Bus namespace with managed
        }
     }
     ```
-2. Create a template parameter file named: **CreateServiceBusPremiumNamespaceParams.json**. 
+1. Create a template parameter file named: **CreateServiceBusPremiumNamespaceParams.json**. 
 
     > [!NOTE]
     > Replace the following values: 
@@ -166,7 +187,7 @@ This section shows you how to create an Azure Service Bus namespace with managed
        }
     }
     ```
-3. Run the following PowerShell command to deploy the template to create a premium Service Bus namespace. Then, retrieve the ID of the Service Bus namespace to use it later. Replace `{MyRG}` with the name of the resource group before running the command.  
+1. Run the following PowerShell command to deploy the template to create a premium Service Bus namespace. Then, retrieve the ID of the Service Bus namespace to use it later. Replace `{MyRG}` with the name of the resource group before running the command.  
 
     ```powershell
     $outputs = New-AzResourceGroupDeployment -Name CreateServiceBusPremiumNamespace -ResourceGroupName {MyRG} -TemplateFile ./CreateServiceBusPremiumNamespace.json -TemplateParameterFile ./CreateServiceBusPremiumNamespaceParams.json
@@ -176,20 +197,7 @@ This section shows you how to create an Azure Service Bus namespace with managed
  
 ### Grant Service Bus namespace identity access to key vault
 
-1. Run the following command to create a key vault with **purge protection** and **soft-delete** enabled. 
-
-    ```powershell
-    New-AzureRmKeyVault -Name "{keyVaultName}" -ResourceGroupName {RGName}  -Location "{location}" -EnableSoftDelete -EnablePurgeProtection    
-    ```
-    
-    (OR)
-    
-    Run the following command to update an **existing key vault**. Specify values for resource group and key vault names before running the command. 
-    
-    ```powershell
-    ($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
-    ``` 
-2. Set the key vault access policy so that the managed identity of the Service Bus namespace can access key value in the key vault. Use the ID of the Service Bus namespace from the previous section. 
+1. Set the key vault access policy so that the managed identity of the Service Bus namespace can access key value in the key vault. Use the ID of the Service Bus namespace from the previous section. 
 
     ```powershell
     $identity = (Get-AzureRmResource -ResourceId $ServiceBusNamespaceId -ExpandProperties).Identity
@@ -201,7 +209,7 @@ This section shows you how to create an Azure Service Bus namespace with managed
 You have done the following steps so far: 
 
 1. Created a premium namespace with a managed identity.
-2. Create a key vault and granted the managed identity access to the key vault. 
+1. Create a key vault and granted the managed identity access to the key vault. 
 
 In this step, you update the Service Bus namespace with key vault information. 
 
@@ -268,14 +276,16 @@ In this step, you update the Service Bus namespace with key vault information.
     }
     ``` 
 
-2. Create a template parameter file: **UpdateServiceBusNamespaceWithEncryptionParams.json**.
+1. Create a template parameter file: **UpdateServiceBusNamespaceWithEncryptionParams.json**.
 
     > [!NOTE]
     > Replace the following values: 
     > - `<ServiceBusNamespaceName>` - Name of your Service Bus namespace
     > - `<Location>` - Location of your Service Bus namespace
     > - `<KeyVaultName>` - Name of your key vault
-    > - `<KeyName>` - Name of the key in the key vault  
+    > - `<KeyName>` - Name of the key in the key vault 
+
+# [Key Vault](#tab/Key-Vault) 
 
     ```json
     {
@@ -296,8 +306,34 @@ In this step, you update the Service Bus namespace with key vault information.
           }
        }
     }
-    ```             
-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. 
+    ```
+
+# [Key Vault Managed HSM](#tab/Key-Vault-Managed-HSM)
+
+    ```json
+    {
+       "$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
+       "contentVersion":"1.0.0.0",
+       "parameters":{
+          "namespaceName":{
+             "value":"<ServiceBusNamespaceName>"
+          },
+          "location":{
+             "value":"<Location>"
+          },
+          "keyName":{
+             "value":"<KeyName>"
+          },
+          "keyVaultUri":{
+             "value":"https://<KeyVaultName>.managedhsm.azure.net"
+          }
+       }
+    }
+    ```
+
+---
+
+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. 
 
     ```powershell
     New-AzResourceGroupDeployment -Name UpdateServiceBusNamespaceWithEncryption -ResourceGroupName {MyRG} -TemplateFile ./UpdateServiceBusNamespaceWithEncryption.json -TemplateParameterFile ./UpdateServiceBusNamespaceWithEncryptionParams.json
@@ -315,27 +351,14 @@ Follow instructions from the [Create a user-assigned managed identity](../active
 > [!NOTE]
 > 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`. 
 
-### Create a key vault and grant access to user-assigned identity 
-
-1. Run the following command to create a key vault with purge protection and soft-delete enabled.
-
-    ```azurepowershell-interactive
-    New-AzureRmKeyVault -Name "{keyVaultName}" -ResourceGroupName {RGName} -Location "{location}" -EnableSoftDelete -EnablePurgeProtection           
-    ```
-    
-    (OR)
+### Grant access to user-assigned identity 
 
-    Run the following command to update an existing key vault. Specify values for resource group and key vault names before running the command.
-
-    ```azurepowershell-interactive
-    ($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            
-    ```
-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.
+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.
 
     ```azurepowershell-interactive
     $servicePrincipal=Get-AzADServicePrincipal -SearchString "ud1"    
     ```
-3. Grant the user-assigned identity access to the key vault by assigning an access policy.     
+1. Grant the user-assigned identity access to the key vault by assigning an access policy.     
 
     ```azurepowershell-interactive
     Set-AzureRmKeyVaultAccessPolicy -VaultName {keyVaultName} -ResourceGroupName {RGName} -ObjectId $servicePrincipal.Id -PermissionsToKeys get,wrapKey,unwrapKey,list    
@@ -374,7 +397,6 @@ This section gives you an example that shows you how to do the following tasks u
                     }
     ```
    
-
 1. Create a JSON file named **CreateServiceBusNamespaceWithUserIdentityAndEncryption.json** with the following content:
 
     ```json
@@ -405,8 +427,7 @@ This section gives you an example that shows you how to do the following tasks u
              "type":"string",
              "metadata":{
                 "description":"KeyName."
-             }
-          },
+             },
          "identity": {
             "type": "Object",
             "defaultValue": {
@@ -452,8 +473,11 @@ This section gives you an example that shows you how to do the following tasks u
        ]
     }        
     ```  
+
 1. Create a template parameter file: **CreateServiceBusNamespaceWithUserIdentityAndEncryptionParams.json**.
 
+# [Key Vault](#tab/Key-Vault) 
+
     ```json
     {
        "$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
@@ -480,6 +504,36 @@ This section gives you an example that shows you how to do the following tasks u
     }
     ```
 
+# [Key Vault Managed HSM](#tab/Key-Vault-Managed-HSM)
+
+    ```json
+    {
+       "$schema":"https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
+       "contentVersion":"1.0.0.0",
+       "parameters":{
+          "namespaceName":{
+             "value":"<ServiceBusNamespaceName>"
+          },
+          "location":{
+             "value":"<Location>"
+          },
+          "keyVaultUri":{
+             "value":"https://<KeyVaultName>.managedhsm.azure.net"
+          },
+          "keyName":{
+             "value":"<KeyName>"
+          },
+          "identity": {
+            "value": {
+                "userAssignedIdentity": "/subscriptions/<AZURE SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP NAME>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER MANAGED IDENTITY NAME>"
+            }
+         }
+       }
+    }
+    ```
+
+---
+
     In the parameter file, replace placeholders with appropriate values.
     
     | Placeholder | value | 
@@ -592,29 +646,29 @@ Here are more details:
     - If a key has been revoked, the key is removed from the record.
     - 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. 
 
-## Considerations when using geo-disaster recovery
+## Considerations when using Geo-Disaster Recovery
 
-### Geo-disaster recovery - encryption with system-assigned identities
+### Geo-Disaster Recovery - encryption with system-assigned identities
 To enable encryption of Microsoft-managed key with a customer managed key, an [access policy](../key-vault/general/secure-your-key-vault.md) is set up for a system-assigned managed identity on the specified Azure KeyVault. This step ensures controlled access to the Azure KeyVault from the Azure Service Bus namespace. Therefore, you need to follow these steps: 
 
 
-- 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
+- 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
     - Break the pairing.
     - [Set up the access policy](../key-vault/general/assign-access-policy-portal.md) for the system-assigned managed identity for both the primary and secondary namespaces to the key vault.
     - Set up encryption on the primary namespace.
     - Re-pair the primary and secondary namespaces.
-- If you're looking to enable Geo-DR on a Service Bus namespace where customer-managed key is already set up, then follow these steps: 
+- If you're looking to enable Geo-Disaster Recovery on a Service Bus namespace where customer-managed key is already set up, then follow these steps: 
     - [Set up the access policy](../key-vault/general/assign-access-policy-portal.md) for the managed identity for the secondary namespace to the key vault.
     - Pair the primary and secondary namespaces.
 
-### Geo-disaster recovery - encryption with user-assigned identities
+### Geo-Disaster Recovery - encryption with user-assigned identities
 Here are a few recommendations: 
 
 1.	Create managed identity and assign Key Vault permissions to your managed identity. 
 2.	Add the identity as a user assigned identity, and enable encryption with the identity on both namespaces. 
 3.	Pair namespaces together 
 
-Conditions for enabling Geo-DR and Encryption with User-Assigned Identities:
+Conditions for enabling Geo-Disaster Recovery and Encryption with User-Assigned Identities:
 
 1.	Secondary namespace must already have Encryption enabled with a User-Assigned identity if it's to be paired with a primary namespace that has Encryption enabled. 
 2.	It isn't possible to enable Encryption on an already paired primary, even if the secondary has a User-Assigned identity associated with the namespace.
@@ -633,4 +687,4 @@ Use the [`resource__versionless_id` or `versionless_id`](https://registry.terraf
 ## Next steps
 See the following articles:
 - [Service Bus overview](service-bus-messaging-overview.md)
-- [Key Vault overview](../key-vault/general/overview.md)
+- [Key Vault overview](../key-vault/general/overview.md)
