Quickstart: Provision and activate a Managed HSM using PowerShell

In this quickstart, you create and activate an Azure Key Vault Managed HSM (Hardware Security Module) with PowerShell. Managed HSM is a fully managed, highly available, single-tenant, standards-compliant cloud service that enables you to safeguard cryptographic keys for your cloud applications, using FIPS 140-2 Level 3 validated HSMs. For more information on Managed HSM, you may review the Overview.

Prerequisites

If you don't have an Azure subscription, create a free account before you begin.

• If you choose to use Azure PowerShell locally:
  • Install the latest version of the Az PowerShell module.
  • Connect to your Azure account using the Connect-AzAccount cmdlet.
• If you choose to use Azure Cloud Shell:
  • See Overview of Azure Cloud Shell for more information.

Create a resource group

A resource group is a logical container into which Azure resources are deployed and managed. Use the Azure PowerShell New-AzResourceGroup cmdlet to create a resource group named myResourceGroup in the norwayeast location.

New-AzResourceGroup -Name "myResourceGroup" -Location "norwayeast"

Get your principal ID

To create a Managed HSM, you need your Microsoft Entra principal ID. To obtain your ID, use the Azure PowerShell Get-AzADUser cmdlet, passing your email address to the "UserPrincipalName" parameter:

Get-AzADUser -UserPrincipalName "<[email protected]>"

Your principal ID is returned in the format, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".

Create a Managed HSM

Creating a Managed HSM is a two-step process:

1. Provision a Managed HSM resource.
2. Activate your Managed HSM by downloading an artifact called the security domain.

Provision a Managed HSM

Use the Azure PowerShell New-AzKeyVaultManagedHsm cmdlet to create a new Managed HSM. You need to provide some information:

• Managed HSM name: A string of 3 to 24 characters that can contain only numbers (0-9), letters (a-z, A-Z), and hyphens (-)

  Important

  Each Managed HSM must have a unique name. Replace <your-unique-managed-hsm-name> with the name of your Managed HSM in the following examples.

• Resource group name: myResourceGroup.

• The location: Norway East.

• Your principal ID: Pass the Microsoft Entra principal ID that you obtained in the last section to the "Administrator" parameter.

New-AzKeyVaultManagedHsm -Name "your-unique-managed-hsm-name" -ResourceGroupName "myResourceGroup" -Location "norwayeast" -Administrator "your-principal-ID" -SoftDeleteRetentionInDays "# of days to retain the managed hsm after softdelete"

The output of this cmdlet shows properties of the newly created Managed HSM. Take note of these two properties:

• Name: The name you provided for the Managed HSM.
• HsmUri: In the example, the HsmUri is https://<your-unique-managed-hsm-name>.managedhsm.azure.net/. Applications that use your vault through its REST API must use this URI.

At this point, your Azure account is the only one authorized to perform any operations on this new HSM.

Activate your Managed HSM

All data plane commands are disabled until the HSM is activated. You will not be able to create keys or assign roles. Only the designated administrators that were assigned during the create command can activate the HSM. To activate the HSM, you must download the Security Domain.

To activate your HSM, you will need:

• To provide a minimum of three RSA key-pairs (up to a maximum of 10)
• To specify the minimum number of keys required to decrypt the security domain (called a quorum)

To activate the HSM, you send at least three (maximum 10) RSA public keys to the HSM. The HSM encrypts the security domain with these keys and sends it back. Once this security domain download is successfully completed, your HSM is ready to use. You also need to specify quorum, which is the minimum number of private keys required to decrypt the security domain.

The following example shows how to use openssl (available for Windows here) to generate three self-signed certificates.

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

Use the Azure PowerShell Export-AzKeyVaultSecurityDomain cmdlet to download the security domain and activate your Managed HSM. The following example uses three RSA key pairs (only public keys are needed for this command) and sets the quorum to two.

Export-AzKeyVaultSecurityDomain -Name "<your-unique-managed-hsm-name>" -Certificates "cert_0.cer", "cert_1.cer", "cert_2.cer" -OutputPath "MHSMsd.ps.json" -Quorum 2

Please store the security domain file and the RSA key pairs securely. You will need them for disaster recovery or for creating another Managed HSM that shares same security domain so the two can share keys.

After successfully downloading the security domain, your HSM will be in an active state and ready for you to use.

Clean up resources

Other quickstarts and tutorials in this collection build upon this quickstart. If you plan to continue on to work with other quickstarts and tutorials, you may want to leave these resources in place.

When no longer needed, you can use the Azure PowerShell Remove-AzResourceGroup cmdlet to remove the resource group and all related resources.

Remove-AzResourceGroup -Name "myResourceGroup"

Next steps

In this quickstart, you created and activated a Managed HSM. To learn more about Managed HSM and how to integrate it with your applications, continue on to these articles:

• Read an Overview of Azure Key Vault
• See the reference for the Azure PowerShell Key Vault cmdlets
• Review the Key Vault security overview