Rotate and revoke a customer-managed key

This article is part three in a four-part tutorial series. Part one provides an overview of customer-managed keys, their features, and considerations before you enable one on your registry. In part two, you learn how to enable a customer-managed key by using the Azure CLI, the Azure portal, or an Azure Resource Manager template. This article walks you through rotating, updating, and revoking a customer-managed key.

Rotate a customer-managed key

To rotate a key, you can either update the key version in Azure Key Vault or create a new key. While rotating the key, you can specify the same identity that you used to create the registry.

Optionally, you can:

• Configure a new user-assigned identity to access the key.
• Enable and specify the registry's system-assigned identity.

Create or update the key version by using the Azure CLI

To create a new key version, run the az keyvault key create command:

# Create new version of existing key
az keyvault key create \
  --name <key-name> \
  --vault-name <key-vault-name>

If you configure the registry to detect key version updates, the customer-managed key is automatically updated within one hour.

If you configure the registry for manual updating for a new key version, run the az-acr-encryption-rotate-key command. Pass the new key ID and the identity that you want to configure.

To update a customer-managed key version manually, you have three options:

• Rotate the key and use a client ID of a managed identity.

  If you're using the key from a different key vault, verify the identity has the get, wrap, and unwrap permissions on that key vault.

  az acr encryption rotate-key \
    --name <registry-name> \
    --key-encryption-key <new-key-id> \
    --identity <client ID of a managed identity>
  

• Rotate the key and use a user-assigned identity.

  Before you use the user-assigned identity, verify that the get, wrap, and unwrap permissions are assigned to it.

  az acr encryption rotate-key \
    --name <registry-name> \
    --key-encryption-key <new-key-id> \
    --identity <id of user assigned identity>
  

• Rotate the key and use a system-assigned identity.

  Before you use the system-assigned identity, verify that the get, wrap, and unwrap permissions are assigned to it.

  az acr encryption rotate-key \
    --name <registry-name> \
    --key-encryption-key <new-key-id> \
    --identity [system]
  

Create or update the key version by using the Azure portal

Use the registry's Encryption settings to update the key vault, key, or identity settings for a customer-managed key.

For example, to configure a new key:

1. In the portal, go to your registry.

2. Under Settings, select Encryption > Change key.

   

3. In Encryption, choose one of the following options:

   • Choose Select from Key Vault, and then either select an existing key vault and key or select Create new. The key that you select is unversioned and enables automatic key rotation.
   • Select Enter key URI, and provide a key identifier directly. You can provide either a versioned key URI (for a key that must be rotated manually) or an unversioned key URI (which enables automatic key rotation).

4. Complete the key selection, and then select Save.

Revoke a customer-managed key

You can revoke a customer-managed encryption key by changing the access policy, by changing the permissions on the key vault, or by deleting the key.

To change the access policy of the managed identity that your registry uses, run the az-keyvault-delete-policy command:

az keyvault delete-policy \
  --resource-group <resource-group-name> \
  --name <key-vault-name> \
  --object-id <key-vault-key-id>

To delete the individual versions of a key, run the az-keyvault-key-delete command. This operation requires the keys/delete permission.

az keyvault key delete  \
  --name <key-vault-name> \
  -- 
  --object-id $identityPrincipalID \                     

Next steps

Advance to the next article to troubleshoot common problems like errors when you're removing a managed identity, 403 errors, and accidental key deletions.