Edit

Full backup and restore and selective key restore

Note

This feature is only available for the resource type managed HSM.

Managed HSM supports creating a full backup of the entire contents of the HSM, including all keys, versions, attributes, tags, and role assignments. The backup process encrypts the data by using cryptographic keys associated with the HSM's security domain.

Backup is a data plane operation. The caller initiating the backup operation must have permission to perform dataAction Microsoft.KeyVault/managedHsm/backup/start/action.

Only the following built-in roles have permission to perform a full backup:

  • Managed HSM Administrator
  • Managed HSM Backup

To back up and restore your Managed HSM, assign a user-assigned managed identity (UAMI) to the Managed HSM service. You can use a UAMI regardless of whether your storage account has public network access or private network access enabled. If the storage account is behind a private endpoint, the UAMI method works with trusted service bypass to allow for backup and restore.

To execute a full backup, provide the following information:

  • HSM name or URL
  • Storage account name
  • Storage account blob storage container
  • User-assigned managed identity

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.

Prerequisites for backing up and restoring by using user-assigned managed identity

  1. Ensure you have Azure CLI version 2.56.0 or later. Run az --version to find the version. If you need to install or upgrade, see Install the Azure CLI.
  2. Create a user-assigned managed identity.
  3. Create a storage account (or use an existing storage account). The storage account can't have an immutability policy applied to it.
  4. If public network access is disabled on your storage account, enable trusted service bypass on the storage account in the Networking tab, under Exceptions.
  5. Provide Storage Blob Data Contributor role access to the user-assigned managed identity created in step 2, by going to the Access Control tab on the portal and selecting Add Role Assignment. Then select managed identity and select the managed identity created in step 2 -> Review + Assign
  6. Create the Managed HSM and associate the managed identity: 
    az keyvault create --hsm-name <hsm-name> -l <location> --retention-days 7 --administrators "<initial-admin>" --mi-user-assigned "/subscriptions/<subscription-id>/resourcegroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<managed-identity-name>"

If you have an existing Managed HSM, associate the managed identity by updating the MHSM with the following command.

 az keyvault update-hsm --hsm-name <hsm-name> --mi-user-assigned "/subscriptions/<subscription-id>/resourcegroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<managed-identity-name>"

Full backup

Backup is a long running operation but it immediately returns a job ID. You can check the status of the backup process by using this job ID. The backup process creates a folder inside the designated container with the following naming pattern: mhsm-{HSM_NAME}-{YYYY}{MM}{DD}{HH}{mm}{SS}. In this pattern, HSM_NAME is the name of the managed HSM being backed up, and YYYY, MM, DD, HH, mm, and SS are the year, month, date, hour, minutes, and seconds of the date and time in UTC when the backup command was received.

While the backup is in progress, the HSM might not operate at full throughput as some HSM partitions are busy performing the backup operation.

Note

Backups to storage accounts with an immutability policy applied aren't supported.

  1. In the Azure portal, navigate to your Managed HSM resource.

  2. In the left menu, under Settings, select Backup.

  3. Provide the storage account and container details, then select Start Backup to initiate the backup.

    Screenshot of the Managed HSM Backup blade in the Azure portal.

Full restore

Full restore restores the contents of the HSM from a previous backup, including all keys, versions, attributes, tags, and role assignments. The process removes everything currently stored in the HSM and returns it to the same state it was in when the source backup was created.

Important

Full restore is a destructive and disruptive operation. Therefore, you must complete a full backup of the HSM you're restoring at least 30 minutes before a restore operation.

Restore is a data plane operation. The caller starting the restore operation must have permission to perform dataAction Microsoft.KeyVault/managedHsm/restore/start/action. The source HSM where you created the backup and the destination HSM where you perform the restore must have the same Security Domain. See more about Managed HSM Security Domain.

You can execute a full restore by using a user-assigned managed identity. To execute a full restore, provide the following information:

  • HSM name or URL
  • Storage account name
  • Storage account blob container
  • User-assigned managed identity
  • Storage container folder name where the source backup is stored

Restore is a long running operation but it immediately returns a Job ID. You can check the status of the restore process by using this Job ID. When the restore process is in progress, the HSM enters a restore mode and all data plane commands (except check restore status) are disabled.

  1. In the Azure portal, navigate to your Managed HSM resource.

  2. In the left menu, under Settings, select Restore.

  3. Provide the storage account, container, and backup folder details, then initiate the restore.

    Screenshot of the Managed HSM Restore blade in the Azure portal.

Selective key restore

Selective key restore restores one key with all its key versions from a previous backup to an HSM. The key must be purged for selective key restore to work. If you're attempting to recover a soft-deleted key, use key recover. Learn more about key recover.

  1. In the Azure portal, navigate to your Managed HSM resource.

  2. In the left menu, under Settings, select Restore, then choose the option to restore a single key from the backup.

Next steps

  • Last updated on