# Azure Key Vault Rotation and Purge Operations

Use this reference for current, source-grounded service behavior and the hard live-operation gates that the lean `SKILL.md` intentionally does not carry.

## What people get wrong

- Treating rotation as safe because Key Vault creates a new version.
- Purging soft-deleted material before proving no dependent service needs recovery.
- Granting purge rights to the same operators who rotate keys or secrets.
- Enabling purge protection without warning that it cannot be disabled.
- Disabling old key versions before re-encryption or dependent services are migrated.

## Officially grounded service shape

Microsoft Learn evidence says soft delete retains deleted vaults and objects for a configurable period, cannot be disabled once enabled, and purge protection prevents permanent deletion until retention elapses. Purge protection cannot be disabled or overridden after enablement. Key rotation should use versioning and rotation policy with dependent-service planning; purge operations require elevated permissions and can be irreversible.

- Soft delete and purge protection are recovery controls with retention windows.
- Purge protection depends on soft delete and prevents purge until retention passes.
- Key rotation creates new versions; consumers must either follow latest version safely or be updated deliberately.
- Secret rotation requires dependent application validation and rollback.
- Azure Policy can audit or deny missing soft delete and purge protection.

## Non-negotiable design rules

- Never request or print key material, secret values, connection strings, or private keys.
- Separate rotation authority from purge authority.
- List dependencies before rotate, disable, delete, recover, or purge.
- Warn explicitly when an operation is irreversible or not fully rollbackable.
- Prefer recovery and quarantine over purge unless destruction is approved and evidenced.

## Minimal safe implementation flow

- Scope vault, object type, object name, environment, owner, and dependent services.
- Collect read-only evidence for soft delete, purge protection, retention, RBAC, object versions, rotation policy, and deleted-object state.
- Classify requested action as rotation, policy update, enable protection, recover, delete, disable, or purge.
- Gate mutation on dependency impact, backup/recovery posture, and explicit approval.
- Verify new version, consumer health, recovery posture, audit events, and remaining risk.

## High-risk assumptions to kill

- Rotation does not prove consumers follow the latest version; pinned key, secret, or certificate versions can break silently after disable/delete.
- Soft delete is not backup. Recovering a vault does not restore all integrated services such as RBAC role assignments or Event Grid subscriptions.
- Purge protection cannot be disabled after enablement and purge can be immediate and irrecoverable when protection does not block it.
- Purge permission should not live with routine rotation automation; separation of duties is the safety control.
- Secret, key, certificate, connection-string, or private-key material must never be pasted into the workflow as evidence.

## Safe command/code verification targets

- Verify vault soft-delete state, purge-protection state, retention period, RBAC/access model, deleted-object state, and object versions.
- Check rotation policy and consumer version-pinning before rotate, disable, delete, recover, or purge.
- Confirm purge authority is narrow, approved, and not reused for normal rotation paths.
- Validate dependent service health against the new version before disabling old versions.
- Label purge and protection changes as irreversible or time-bound where Microsoft Learn documents those constraints.

## Safe verification targets

- Soft delete and purge protection state are known and documented.
- Purge role assignments are narrow, JIT where possible, and not routine automation.
- Rotation policy aligns with compliance and consumer behavior.
- Dependent services are tested against new key/secret versions.
- Recovery or purge decision has owner approval and retention/irreversibility caveat.

## When to push back

- The user asks to purge without dependency and approval evidence.
- The user asks to paste or export secret/key material.
- Rotation would break pinned-version consumers with no migration plan.
- Purge protection or retention implications are not understood by the approver.

# Documentation and Evidence Path

## Preferred evidence order

1. Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior.
2. Sampled read-only Azure evidence, when safely available, for current configured-environment observations.
3. Sanitized user-provided evidence.
4. Clearly labeled inference.

## What each evidence type can prove

- Microsoft Learn documentation can prove documented service behavior, supported concepts, limitations, and recommended patterns.
- Sampled read-only evidence can prove the sampled configured state at the time observed.
- Sanitized user evidence can prove only what the snippet shows.
- None of these alone prove broad regional availability, future success, full account posture, or production readiness.

## Safe usage pattern

- State whether each claim is documentation-based, sampled-current-state, user-provided, or inference.
- Use read-only queries before recommending changes.
- Do not include sensitive internal identifiers, tenant identifiers, subscription identifiers, or secrets in committed docs or final findings.
- If no sampled evidence is available, say the review is documentation-based and list the exact evidence still needed.

## Live-operation rule

For live operations, documentation is never enough. Require target confirmation, current-state evidence, explicit approval, rollback constraints, and post-action verification.

# Official Sources

Use these sources to ground the skill. Microsoft Learn documentation proves documented Azure behavior; it does not prove the user's tenant, subscription, RBAC, quota, deployed resources, current cost, vault state, app health, or production readiness.

## Primary Microsoft Learn sources

- https://learn.microsoft.com/azure/key-vault/general/key-vault-recovery
- https://learn.microsoft.com/azure/key-vault/general/soft-delete-overview
- https://learn.microsoft.com/azure/key-vault/general/secure-key-vault
- https://learn.microsoft.com/azure/key-vault/keys/how-to-configure-key-rotation
- https://learn.microsoft.com/azure/key-vault/keys/secure-keys
- https://learn.microsoft.com/azure/key-vault/policy-reference

## Grounding notes

- Documentation-based claim: Microsoft Learn evidence says soft delete retains deleted vaults and objects for a configurable period, cannot be disabled once enabled, and purge protection prevents permanent deletion until retention elapses. Purge protection cannot be disabled or overridden after enablement. Key rotation should use versioning and rotation policy with dependent-service planning; purge operations require elevated permissions and can be irreversible.
- Current-state claim: requires sampled read-only Azure evidence or sanitized user-provided evidence.
- Live-operation claim: requires target, principal, approval, preflight evidence, rollback constraints, and post-action verification.
- Inference: allowed only when labeled and tied to observed fields or documented behavior.
- Do not include sensitive internal identifiers or secret material in findings.

## Source use rules

- Prefer Microsoft Learn documentation through the user's configured documentation MCP for current Azure service behavior.
- Use sampled read-only Azure evidence only to validate current configured-environment observations.
- If documentation and sampled evidence appear to conflict, report both and stop short of a production-ready verdict.
- Re-check official sources before changing high-risk guidance, because cloud behavior and feature availability can change.

## Current Microsoft Learn deltas checked on 2026-06-05

- Soft delete is enabled by default for new vaults and cannot be disabled after enablement.
- Purge protection is not enabled by default, but once enabled it cannot be disabled or bypassed during the retention period.
- Key rotation creates a new key version; it does not re-encrypt dependent data by itself, so old and new versions may both be needed during rewrap/migration.
- Recovering a soft-deleted vault does not automatically restore every integrated artifact such as role assignments or event subscriptions.

# Permission Model: Azure Live Key Vault Rotation Purge Guard

## Evidence-variable convention

Shell variables in examples are local operator placeholders from an approved change record or already configured shell context. Do not commit real values, and redact them from shared evidence unless disclosure is explicitly approved.

## Rotation operator role — no delete, no purge

```json
{
  "Name": "Key Vault Rotation Guard",
  "IsCustom": true,
  "Description": "Rotate keys and update rotation policies. Cannot delete or purge keys/secrets/certificates. Cannot purge the vault itself. Cannot disable soft-delete.",
  "Actions": [
    "Microsoft.KeyVault/vaults/read",
    "Microsoft.KeyVault/vaults/keys/read",
    "Microsoft.KeyVault/vaults/secrets/read"
  ],
  "NotActions": [
    "Microsoft.KeyVault/vaults/purge/action",
    "Microsoft.KeyVault/vaults/delete",
    "Microsoft.KeyVault/vaults/write",
    "Microsoft.KeyVault/vaults/accessPolicies/write"
  ],
  "DataActions": [
    "Microsoft.KeyVault/vaults/keys/read",
    "Microsoft.KeyVault/vaults/keys/rotate/action",
    "Microsoft.KeyVault/vaults/keys/rotationpolicy/read",
    "Microsoft.KeyVault/vaults/keys/rotationpolicy/write",
    "Microsoft.KeyVault/vaults/secrets/getSecret/action"
  ],
  "NotDataActions": [
    "Microsoft.KeyVault/vaults/keys/delete",
    "Microsoft.KeyVault/vaults/keys/purge/action",
    "Microsoft.KeyVault/vaults/secrets/delete",
    "Microsoft.KeyVault/vaults/secrets/purge/action",
    "Microsoft.KeyVault/vaults/certificates/delete",
    "Microsoft.KeyVault/vaults/certificates/purge/action"
  ],
  "AssignableScopes": [
    "$APPROVED_KEY_VAULT_SCOPE"
  ]
}
```

Nearest built-in roles: `Key Vault Crypto Officer` (keys), `Key Vault Secrets Officer` (secrets).
Both include delete — prefer the custom role above for rotation-only scenarios.

**Action vs DataAction distinction (security-critical)**:
`Microsoft.KeyVault/vaults/purge/action` is a **control-plane Action** that purges the
soft-deleted **vault** itself (irreversible). It is **not** a DataAction and is not blocked
by `NotDataActions`. It must be in `NotActions`. Certificate operations exist on both planes;
this role blocks both. Do not assume `NotDataActions` covers all destructive Key Vault paths.

## Purge-protection enablement (separate, PIM-gated operation)

Requires `Microsoft.KeyVault/vaults/write` on the vault resource.
Assign via PIM with justification. Maximum 1-hour activation window.

**IRREVERSIBILITY WARNING**: Once `enablePurgeProtection: true` is set on a vault,
it cannot be unset. All soft-deleted objects are protected from permanent deletion
until the retention period (7–90 days) expires. This is a one-way door.

## Do not assign

- `Key Vault Administrator` standing (includes purge rights)
- `Microsoft.KeyVault/vaults/purge/action` to rotation operators
- `Microsoft.KeyVault/vaults/accessPolicies/write` to non-admins (legacy access policy model)

Use exact resource scopes from approved change records; do not paste raw subscription identifiers into chat.

# Preflight Commands: Azure Live Key Vault Rotation Purge Guard

Use shell variables for examples instead of raw identifiers. Populate them from an approved change record or already configured shell context; never paste tenant, subscription, resource, or secret values into chat.

## Evidence-variable convention

Variables such as $AZURE_RESOURCE_GROUP_NAME, $APP_SERVICE_APP_NAME, or $KEY_VAULT_NAME are local operator placeholders. Do not commit real values, and redact them from shared evidence unless the change record explicitly allows disclosure.

Run these before any Key Vault rotation or purge operation.

## 1. Confirm identity and vault target

```bash
az account show --query "{subscription:id, name:name, user:user.name}"
az keyvault show -n $KEY_VAULT_NAME -g $AZURE_RESOURCE_GROUP_NAME \
  --query "{name:name, enableSoftDelete:properties.enableSoftDelete, enablePurgeProtection:properties.enablePurgeProtection, softDeleteRetentionInDays:properties.softDeleteRetentionInDays}"
```

## 2. List key versions and identify current/active

```bash
az keyvault key list-versions --vault-name $KEY_VAULT_NAME -n $KEY_VAULT_KEY_NAME \
  --query "[].{kid:kid, enabled:attributes.enabled, created:attributes.created, expires:attributes.expires}"
```

## 3. Check rotation policy

```bash
az keyvault key rotation-policy show --vault-name $KEY_VAULT_NAME -n $KEY_VAULT_KEY_NAME
```

## 4. List soft-deleted keys (purge risk check)

```bash
az keyvault key list-deleted --vault-name $KEY_VAULT_NAME \
  --query "[].{name:name, deletedDate:attributes.deletedDate, scheduledPurgeDate:attributes.scheduledPurgeDate}"
```

## 5. Verify which services use this key (impact analysis)

```bash
# Check disk encryption sets using this vault
az disk-encryption-set list --query \
  "[?activeKey.sourceVault.id contains '$KEY_VAULT_NAME'].{name:name, id:id}"
# Check Storage accounts with CMK
az storage account list --query \
  "[?encryption.keyVaultProperties.keyVaultUri contains '$KEY_VAULT_NAME'].{name:name}"
```

## 6. Confirm backup exists before any key version operation

```bash
az keyvault key backup --vault-name $KEY_VAULT_NAME -n $KEY_VAULT_KEY_NAME -f $KEY_VAULT_KEY_NAME-backup.json
```


## Read-only configured evidence labels

Treat key, secret, certificate, and Managed HSM metadata reads as sampled read-only Azure evidence. Do not print secret values. A successful metadata read proves only the sampled vault/object state, not tenant-wide Key Vault posture.

# Rollback Playbook: Azure Live Key Vault Rotation Purge Guard

## Evidence-variable convention

Variables such as $APPROVED_AZURE_SCOPE, $ASSIGNEE_LOOKUP_VALUE, $ROLE_DEFINITION_NAME, $KEY_VAULT_NAME, and $KEY_VAULT_KEY_NAME are local operator placeholders. Do not commit real values, and redact them from shared evidence unless the change record explicitly allows disclosure.

## Restore a key from backup

```bash
# Restore the key backup created during preflight
az keyvault key restore --vault-name $KEY_VAULT_NAME -f $KEY_VAULT_KEY_NAME-backup.json
```

Note: key backup/restore only works within the same geography and subscription security boundary.

## Re-enable a disabled key version

```bash
az keyvault key set-attributes --vault-name $KEY_VAULT_NAME -n $KEY_VAULT_KEY_NAME \
  --version <VERSION_ID> --enabled true
```

## Recover a soft-deleted key (before purge window expires)

```bash
# List soft-deleted keys
az keyvault key list-deleted --vault-name $KEY_VAULT_NAME

# Recover
az keyvault key recover --vault-name $KEY_VAULT_NAME -n $KEY_VAULT_KEY_NAME
```

## Revert rotation policy to previous settings

```bash
# Update rotation policy with restored values
az keyvault key rotation-policy update \
  --vault-name $KEY_VAULT_NAME \
  -n $KEY_VAULT_KEY_NAME \
  --value @previous-rotation-policy.json
```

## Rollback limitations

- **Purge is permanent and irreversible.** Once a key is purged, it cannot be recovered by any path.
- Purge protection prevents purge until the retention window expires — this is intentional and cannot be bypassed.
- Data encrypted with a deleted/rotated key becomes unreadable if the old key version is permanently deleted.
- Services using this key (disk encryption sets, CMK storage) must be re-keyed if the key version changes.

# Safety Checklist

## Evidence labels

- `documentation-based`: grounded in Microsoft Learn or listed official documentation.
- `sampled-current-state`: grounded in read-only Azure or Kubernetes observations from the user's configured tools.
- `user-provided`: grounded in sanitized snippets supplied by the user.
- `inference`: reasoned from evidence but not directly proven.

## Mutation boundary

- Default to read-only review.
- Do not perform create, update, delete, rotate, purge, recover, apply, swap, reset, complete, deploy, assign, revoke, deallocate, quota, budget, or policy changes unless the user explicitly asks and approval is clear.
- Prefer preview, what-if, dry-run, status, describe, list, show, diff, activity-log, and policy evaluation evidence before any mutation.

## Credential and data boundary

- Never ask users to paste credentials, tokens, tenant IDs, subscription IDs, customer data, private keys, kubeconfig contents, CA requester credentials, secret values, connection strings, or raw environment dumps.
- Summarize sensitive evidence by field presence, control state, and risk; do not reproduce secret material.

## Risk gates

- Stop on ambiguous target, ambiguous principal, missing approval, missing rollback, missing financial owner, or missing asset owner for high-impact assets.
- Treat broad permissions, permanent privileged access, public exposure, purge authority, destructive deployment behavior, quota increases, budget automation, and production slot swaps as high-risk.
- Separate documented product behavior from sampled configured-environment evidence.

## Asset-specific hard line

Purge protection enablement is irreversible, purge is permanent when allowed, and key/secret rotation can break dependent workloads. Never grant purge rights to routine rotation operators or mutate production vault lifecycle controls without owner approval and dependency evidence.

# Workflow and Output Contract

## Execution flow

1. Scope the exact target, environment boundary, owner, requested operation, approval state, and rollback owner.
2. Load `official-sources.md`, then the component operations guide for service behavior and risk gates.
3. Gather sampled read-only evidence only when available and safe.
4. Compare observed posture against documented behavior, least-privilege expectations, and live-operation safety rules.
5. Refuse or defer mutation if target, approval, rollback, or evidence is incomplete.
6. Return a verdict with evidence level, blockers, safe next actions, and open questions.

## Required output

- `verdict`: pass, warn, fail, or blocked.
- `evidence_level`: documentation-based, sampled-current-state, user-provided, inference, or mixed.
- `scope`: what was reviewed and what was not reviewed.
- `approval_status`: explicit approval, missing approval, or not applicable for read-only review.
- `blockers`: issues that prevent a safe or production-ready conclusion.
- `findings`: severity-labeled risks with source labels.
- `rollback_posture`: exact rollback path or explicit non-reversibility caveat.
- `safe_next_actions`: reversible actions first; mutation only with explicit approval.
- `open_questions`: missing facts that would change the verdict.

## Stress checks

- What assumption would make this recommendation unsafe?
- Which role, policy, budget, quota, deployment, swap, or purge action has the largest blast radius?
- What evidence would disprove the claimed readiness?
- Is the answer accidentally treating documentation as environment-specific proof?

## Response discipline

Use Microsoft Learn documentation through the user's configured documentation MCP for documented Azure behavior. Use sampled read-only Azure evidence only for current configured-environment observations and label it as sampled evidence.