Edit

Share via

Quickstart: Provision and activate a Managed HSM using Azure CLI

  • Article

In this quickstart, you will create and activate an Azure Key Vault Managed HSM (Hardware Security Module) with Azure CLI. 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

To complete the steps in this article, you must have:

  • A subscription to Microsoft Azure. If you do not have one, you can sign up for a free trial.
  • The Azure CLI version 2.25.0 or later. Run az --version to find the version. If you need to install or upgrade, see Install the Azure CLI.

Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Button to launch Azure Cloud Shell.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Screenshot that shows the Cloud Shell button in the Azure portal

To use Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block (or command block) to copy the code or command.

  3. Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code or command.

Sign in to Azure

To sign in to Azure using the CLI, you can type:

az login

Create a resource group

A resource group is a logical container into which Azure resources are deployed and managed. The following example creates a resource group named ContosoResourceGroup in the eastus2 location.

az group create --name "ContosoResourceGroup" --location eastus2

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 az keyvault create command to create a Managed HSM. This script has three mandatory parameters: a resource group name, an HSM name, and the geographic location.

You need to provide following inputs to create a Managed HSM resource:

  • A resource group where it will be placed in your subscription.
  • Azure location.
  • A list of initial administrators.

The following example creates an HSM named ContosoMHSM, in the resource group ContosoResourceGroup, residing in the East US 2 location, with the current signed in user as the only administrator, with 7 days retention period for soft-delete. The Managed HSM will continue to be billed until it is purged in a soft-delete period. For more information, see Managed HSM soft-delete and purge protection and read more about Managed HSM soft-delete.

oid=$(az ad signed-in-user show --query id -o tsv)
az keyvault create --hsm-name "ContosoMHSM" --resource-group "ContosoResourceGroup" --location "eastus2" --administrators $oid --retention-days 7

Note

If you are using Managed Identities as the initial admins of your Managed HSM, you should input the OID/PrincipalID of the Managed Identities after '--administrators' and not the ClientID.

Note

The create command can take a few minutes. Once it returns successfully you are ready to activate your HSM.

Warning

Managed HSM instances are considered always-in-use. If you choose to enable purge protection using the --enable-purge-protection flag, you will be billed for the entirety of the retention period.

The output of this command shows properties of the Managed HSM that you've created. The two most important properties are:

  • name: In the example, the name is ContosoMHSM. You'll use this name for other commands.
  • hsmUri: In the example, the URI is 'https://contosohsm.managedhsm.azure.net.' Applications that use your HSM through its REST API must use this URI.

Your Azure account is now authorized to perform any operations on this Managed HSM. As of yet, nobody else is authorized.

Activate your Managed HSM

All data plane commands are disabled until the HSM is activated. For example, 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 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

Note

Even if the certificate has "expired," it can still be used to restore the security domain.

Important

Create and store the RSA key pairs and security domain file generated in this step securely.

Use the az keyvault security-domain download command 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.

az keyvault security-domain download --hsm-name ContosoMHSM --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

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 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 subsequent quickstarts and tutorials, you may wish to leave these resources in place.

When no longer needed, you can use the az group delete command to remove the resource group, and all related resources. You can delete the resources as follows:

az group delete --name ContosoResourceGroup

Warning

Deleting the resource group puts the Managed HSM into a soft-deleted state. The Managed HSM will continue to be billed until it is purged. See Managed HSM soft-delete and purge protection

Next steps

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