Edit

Share via

Azure Key Vault recovery management with soft delete and purge protection

  • Article

This article covers two recovery features of Azure Key Vault, soft delete and purge protection. This document provides an overview of these features, and shows you how to manage them through the Azure portal, Azure CLI, and Azure PowerShell.

Important

If a key vault does not have soft-delete protection enabled, deleting a key deletes it permanently. Customers are strongly encouraged to turn on soft delete enforcement for their vaults via Azure Policy.

For more information about Key Vault, see

Prerequisites

  • An Azure subscription - create one for free

  • Azure PowerShell.

  • Azure CLI

  • A Key Vault - you can create one using Azure portal Azure CLI, or Azure PowerShell

  • The user needs the following permissions (at subscription level) to perform operations on soft-deleted vaults:

    Permission Description
    Microsoft.KeyVault/locations/deletedVaults/read View the properties of a soft deleted key vault
    Microsoft.KeyVault/locations/deletedVaults/purge/action Purge a soft deleted key vault
    Microsoft.KeyVault/locations/operationResults/read To check purging state of vault
    Key Vault Contributor To recover soft-deleted vault

What are soft-delete and purge protection

Soft delete and purge protection are two different key vault recovery features.

Soft delete is designed to prevent accidental deletion of your key vault and keys, secrets, and certificates stored inside key vault. Think of soft-delete like a recycle bin. When you delete a key vault or a key vault object, it remains recoverable for a user configurable retention period or a default of 90 days. Key vaults in the soft deleted state can also be purged (permanently deleted), allowing you to recreate key vaults and key vault objects with the same name. Both recovering and deleting key vaults and objects require elevated access policy permissions. Once soft delete has been enabled, it cannot be disabled.

It is important to note that key vault names are globally unique, so you aren't able to create a key vault with the same name as a key vault in the soft deleted state. Similarly, the names of keys, secrets, and certificates are unique within a key vault. You aren't able to create a secret, key, or certificate with the same name as another in the soft deleted state.

Purge protection is designed to prevent the deletion of your key vault, keys, secrets, and certificates by a malicious insider. Think of it as a recycle bin with a time based lock. You can recover items at any point during the configurable retention period. You will not be able to permanently delete or purge a key vault until the retention period elapses. Once the retention period elapses the key vault or key vault object is purged automatically.

Note

Purge Protection is designed so that no administrator role or permission can override, disable, or circumvent purge protection. When purge protection is enabled, it cannot be disabled or overridden by anyone including Microsoft. This means you must recover a deleted key vault or wait for the retention period to elapse before reusing the key vault name.

For more information about soft-delete, see Azure Key Vault soft-delete overview

Key Vault (CLI)

  • Verify if a key-vault has soft-delete enabled

    az keyvault show --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}

  • Enable soft-delete on key-vault

    All new key vaults have soft delete enabled by default. If you currently have a key vault that does not have soft delete enabled, use the following command to enable soft delete.

    az keyvault update --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME} --enable-soft-delete true

  • Delete key vault (recoverable if soft delete is enabled)

    az keyvault delete --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}

  • List all soft-deleted key vaults

    az keyvault list-deleted --subscription {SUBSCRIPTION ID} --resource-type vault

  • Recover soft-deleted key-vault

    az keyvault recover --subscription {SUBSCRIPTION ID} -n {VAULT NAME}

  • Purge soft-deleted key vault (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR KEY VAULT)

    az keyvault purge --subscription {SUBSCRIPTION ID} -n {VAULT NAME}

  • Enable purge-protection on key-vault

    az keyvault update --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME} --enable-purge-protection true

Certificates (CLI)

  • Grant access to purge and recover certificates

    az keyvault set-policy --upn user@contoso.com --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}  --certificate-permissions recover purge

  • Delete certificate

    az keyvault certificate delete --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {CERTIFICATE NAME}

  • List deleted certificates

    az keyvault certificate list-deleted --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME}

  • Recover deleted certificate

    az keyvault certificate recover --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {CERTIFICATE NAME}

  • Purge soft-deleted certificate (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR CERTIFICATE)

    az keyvault certificate purge --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {CERTIFICATE NAME}

Keys (CLI)

  • Grant access to purge and recover keys

    az keyvault set-policy --upn user@contoso.com --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}  --key-permissions recover purge

  • Delete key

    az keyvault key delete --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {KEY NAME}

  • List deleted keys

    az keyvault key list-deleted --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME}

  • Recover deleted key

    az keyvault key recover --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {KEY NAME}

  • Purge soft-deleted key (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR KEY)

    az keyvault key purge --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {KEY NAME}

Secrets (CLI)

  • Grant access to purge and recover secrets

    az keyvault set-policy --upn user@contoso.com --subscription {SUBSCRIPTION ID} -g {RESOURCE GROUP} -n {VAULT NAME}  --secret-permissions recover purge

  • Delete secret

    az keyvault secret delete --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {SECRET NAME}

  • List deleted secrets

    az keyvault secret list-deleted --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME}

  • Recover deleted secret

    az keyvault secret recover --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {SECRET NAME}

  • Purge soft-deleted secret (WARNING! THIS OPERATION WILL PERMANENTLY DELETE YOUR SECRET)

    az keyvault secret purge --subscription {SUBSCRIPTION ID} --vault-name {VAULT NAME} --name {SECRET NAME}

Next steps