Quickstart: Create a Managed HSM using an ARM template

  • Article

This quickstart describes how to use an Azure Resource Manager template (ARM template) to create an Azure Key Vault managed HSM. Managed HSM is a fully managed, highly available, single-tenant, standards-compliant cloud service that enables you to safeguards cryptographic keys for your cloud applications, using FIPS 140-2 Level 3 validated HSMs.

An Azure Resource Manager template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax. You describe your intended deployment without writing the sequence of programming commands to create the deployment.

If your environment meets the prerequisites and you're familiar with using ARM templates, select the Deploy to Azure button. The template will open in the Azure portal.

Button to deploy the Resource Manager template to Azure.

Prerequisites

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

  • If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Review the template

The template used in this quickstart is from Azure Quickstart Templates:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.5.6.12127",
      "templateHash": "9933229425431379390"
    }
  },
  "parameters": {
    "managedHSMName": {
      "type": "string",
      "metadata": {
        "description": "String specifying the name of the managed HSM."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "String specifying the Azure location where the managed HSM should be created."
      }
    },
    "initialAdminObjectIds": {
      "type": "array",
      "metadata": {
        "description": "Array specifying the objectIDs associated with a list of initial administrators."
      }
    },
    "tenantId": {
      "type": "string",
      "defaultValue": "[subscription().tenantId]",
      "metadata": {
        "description": "String specifying the Azure Active Directory tenant ID that should be used for authenticating requests to the managed HSM."
      }
    },
    "softRetentionInDays": {
      "type": "int",
      "defaultValue": 7,
      "maxValue": 90,
      "minValue": 7,
      "metadata": {
        "description": "Specifies the number of days that managed Key Vault will be kept recoverable if deleted. If you do not want to have soft delete enabled, set value to 0."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/managedHSMs",
      "apiVersion": "2021-04-01-preview",
      "name": "[parameters('managedHSMName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_B1",
        "family": "B"
      },
      "properties": {
        "enableSoftDelete": "[greater(parameters('softRetentionInDays'), 0)]",
        "softDeleteRetentionInDays": "[if(equals(parameters('softRetentionInDays'), 0), null(), parameters('softRetentionInDays'))]",
        "enablePurgeProtection": false,
        "tenantId": "[parameters('tenantId')]",
        "initialAdminObjectIds": "[parameters('initialAdminObjectIds')]",
        "publicNetworkAccess": "Enabled",
        "networkAcls": {
          "bypass": "None",
          "defaultAction": "Allow"
        }
      }
    }
  ]
}

The Azure resource defined in the template is:

  • Microsoft.KeyVault/managedHSMs: Create an Azure Key Vault Managed HSM.

Deploy the template

The template requires the object ID associated with your account. To find it, use the Azure CLI az ad user show command, passing your email address to the --id parameter. You can limit the output to the object ID only with the --query parameter.

az ad user show --id <your-email-address> --query "objectId"

You may also need your tenant ID. To find it, use the Azure CLI az ad user show command. You can limit the output to the tenant ID only with the --query parameter.

az account show --query "tenantId"

You can now deploy the ARM template:

  1. Select the following image to sign in to Azure and open a template. The template creates a Managed HSM.

    Button to deploy the Resource Manager template to Azure.

  2. Select or enter the following values. Unless specified, use the default value to create the Managed HSM.

    • Subscription: Select an Azure subscription.
    • Resource group: Select Create new, enter "myResourceGroup" as the name, and then select OK.
    • Location: Select a location. For example, China East 2.
    • managedHSMName: Enter a name for your Managed HSM.
    • Tenant ID: The template function automatically retrieves your tenant ID; don't change the default value. If there's no value, enter the Tenant ID that you retrieved above.
    • initialAdminObjectIds: Enter the Object ID that you retrieved above.

  3. Select Purchase. After the Managed HSM has been deployed successfully, you get a notification:

The Azure portal is used to deploy the template. In addition to the Azure portal, you can also use the Azure PowerShell, Azure CLI, and REST API. To learn other deployment methods, see Deploy templates.

Validate the deployment

You can verify that the managed HSM was created with the Azure CLI az keyvault list command. You'll find the output easier to read if you format the results as a table:

az keyvault list -o table

You should see the name of your newly created managed HSM.

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 Azure CLI az group delete command to remove the resource group and all related resources:

az group delete --name "myResourceGroup"

Warning

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

Next steps

In this quickstart, you created a Managed HSM. This Managed HSM won't be fully functional until it's activated. See Activate your Managed HSM to learn how to activate your HSM.