Feedback Edit

Configure key auto-rotation in Azure Key Vault

  • Article
  • 3 minutes to read

Overview

Automated key rotation in Key Vault allows users to configure Key Vault to automatically generate a new key version at a specified frequency. You can use rotation policy to configure rotation for each individual key. Our recommendation is to rotate encryption keys at least every two years to meet cryptographic best practices.

This feature enables end-to-end zero-touch rotation for encryption at rest for Azure services with customer-managed key (CMK) stored in Azure Key Vault. Please refer to specific Azure service documentation to see if the service covers end-to-end rotation.

Pricing

There's an additional cost per scheduled key rotation. For more information, see Azure Key Vault pricing page

Permissions required

Key Vault key rotation feature requires key management permissions. You can assign a "Key Vault Crypto Officer" role to manage rotation policy and on-demand rotation.

For more information on how to use Key Vault RBAC permission model and assign Azure roles, see: Use an Azure RBAC to control access to keys, certificates and secrets

Note

If you use an access policies permission model, it is required to set 'Rotate', 'Set Rotation Policy', and 'Get Rotation Policy' key permissions to manage rotation policy on keys.

Key rotation policy

The key rotation policy allows users to configure rotation and Event Grid notifications near expiry notification.

Key rotation policy settings:

  • Expiry time: key expiration interval. It's used to set expiration date on newly rotated key. It doesn't affect a current key.
  • Enabled/disabled: flag to enable or disable rotation for the key
  • Rotation types:
    • Automatically renew at a given time after creation (default)
    • Automatically renew at a given time before expiry. It requires 'Expiry Time' set on rotation policy and 'Expiration Date' set on the key.
  • Rotation time: key rotation interval, the minimum value is seven days from creation and seven days from expiration time
  • Notification time: key near expiry event interval for Event Grid notification. It requires 'Expiry Time' set on rotation policy and 'Expiration Date' set on the key.

Rotation policy configuration

Configure key rotation policy

Configure key rotation policy during key creation.

Configure rotation during key creation

Configure rotation policy on existing keys.

Configure rotation on existing key

Azure CLI

Save key rotation policy to a file. Key rotation policy example:

{
  "lifetimeActions": [
    {
      "trigger": {
        "timeAfterCreate": "P18M",
        "timeBeforeExpiry": null
      },
      "action": {
        "type": "Rotate"
      }
    },
    {
      "trigger": {
        "timeBeforeExpiry": "P30D"
      },
      "action": {
        "type": "Notify"
      }
    }
  ],
  "attributes": {
    "expiryTime": "P2Y"
  }
}

Set rotation policy on a key passing previously saved file.

az keyvault key rotation-policy update --vault-name <vault-name> --name <key-name> --value </path/to/policy.json>

Rotation on demand

Key rotation can be invoked manually.

Portal

Click 'Rotate Now' to invoke rotation.

Rotation on-demand

Azure CLI

az keyvault key rotate --vault-name <vault-name> --name <key-name>

Configure key near expiry notification

Configuration of expiry notification for Event Grid key near expiry event. You can configure notification with days, months and years before expiry to trigger near expiry event.

Configure Notification

For more information about Event Grid notifications in Key Vault, see Azure Key Vault as Event Grid source

Configure key rotation with ARM template

Key rotation policy can also be configured using ARM templates.

Note

It requires 'Key Vault Contributor' role on Key Vault configured with Azure RBAC to deploy key through management plane.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "vaultName": {
            "type": "String",
            "metadata": {
                "description": "The name of the key vault to be created."
            }
        },
        "keyName": {
            "type": "String",
            "metadata": {
                "description": "The name of the key to be created."
            }
        },
        "rotatationTimeAfterCreate": {
            "defaultValue": "P18M",
            "type": "String",
            "metadata": {
                "description": "Time duration to trigger key rotation. i.e. P30D, P1M, P2Y"
            }
        },
        "expiryTime": {
            "defaultValue": "P2Y",
            "type": "String",
            "metadata": {
                "description": "The expiry time for new key version. i.e. P90D, P2M, P3Y"
            }
        },
        "notifyTime": {
            "defaultValue": "P30D",
            "type": "String",
            "metadata": {
                "description": "Near expiry Event Grid notification. i.e. P30D"
            }
        }

    },
    "resources": [
        {
            "type": "Microsoft.KeyVault/vaults/keys",
            "apiVersion": "2021-06-01-preview",
            "name": "[concat(parameters('vaultName'), '/', parameters('keyName'))]",
            "location": "[resourceGroup().location]",
            "properties": {
                "vaultName": "[parameters('vaultName')]",
                "kty": "RSA",
                "rotationPolicy": {
                    "lifetimeActions": [
                        {
                            "trigger": {
                                "timeAfterCreate": "[parameters('rotatationTimeAfterCreate')]",
                                "timeBeforeExpiry": ""
                            },
                            "action": {
                                "type": "Rotate"
                            }
                        },
                        {
                            "trigger": {
                                "timeBeforeExpiry": "[parameters('notifyTime')]"
                            },
                            "action": {
                                "type": "Notify"
                            }
                        }

                    ],
                    "attributes": {
                        "expiryTime": "[parameters('expiryTime')]"
                    }
                }
            }
        }
    ]
}

Resources