Rotation policies

Vault Enterprise includes a centralized automated credential rotation system to enforce automated, scheduled or period-based rotations for onboarded credentials. You can define how Vault Enterprise handles execution failures and retry logic by configuring rotation policies. Rotation policies specify limits for backoff attempts and requeue cycles before Vault marks a rotation as orphaned. Rotation policies do not affect Vault access policies.

Vault Enterprise currently supports policy rotation for the following workflows:

• LDAP secrets static roles
  Enterprise
• OS secrets accounts
  Enterprise

Once you create a rotation policy, you can assign that policy to new and existing roles. Vault uses the policy instructions to manage retry and failure logic when automatically rotating credentials for the associated role.

See the automated rotation documentation for an overview of Vault's rotation system.

Rotation policy parameters

Vault defines rotation policies in JSON and supports the following configuration parameters:

• max_retries_per_cycle (int:<required>) - The maximum number of times Vault Enterprise should apply backoff for rotation entries after a rotation failure.

• max_retry_cycles (int:<required>) - The maximum number of times Vault Enterprise should requeue rotation entries after reaching the max_retries_per_cycle limit. Vault Enterprise requeues rotation entries to their next scheduled rotation.

Example rotation policy

{
  "max_retry_cycles": 3,
  "max_retries_per_cycle": 3
}

The example policy limits exponential backoff for a single rotation cycle to 3 attempts within a single retry cycle. If rotations fail after 3 attempts, Vault Enterprise will requeue the rotation entry with its original schedule and repeat the exponential backoff retry cycle. The example policy also limits the number of requeue attempts to a total of 3 times. If the rotation entry still fails after all 3 requeue attempts (total of 9 retry attempts), Vault marks the credential rotation as orphaned and halts any further automated rotation attempts.

See the rotation policy API documentation for further details.

Default rotation policy

Vault applies a default rotation policy for supported plugins if you choose not to assign a custom rotation policy. The default policy limits retries with a backoff to 6 attempts and re-queues with the original rotation schedule to 3 attempts:

{
  "max_retry_cycles": 3,
  "max_retries_per_cycle": 6
}

Usage

First, create the rotation policy:

vault write sys/policies/rotation/custom-ldap-policy \
    max_retry_cycles=4 \
    max_retries_per_cycle=5

Once Vault stores the policy, you can assign rotation policies when configuring a new credential. For example, to associate the rotation policy custom-ldap-policy with a new LDAP role named alice:

vault write ldap/static-role/alice \
    dn="cn=alice,ou=users,dc=example,dc=com" \
    username="alice" \
    rotation_period="24h" \
    rotation_policy="custom-ldap-policy"

If you do not provide a rotation policy when creating a role, Vault uses the default policy. You can unset an assigned policy and force Vault to use the default policy by updating the role to unset the rotation_policy field:

vault write ldap/static-role/alice \
    dn="cn=alice,ou=users,dc=example,dc=com" \
    username="alice" \
    rotation_period="24h" \
    rotation_policy=""

Vault Enterprise fetches the latest policy updates on each requeue cycle, which means you may not see policy updates reflected immediately in Vault behavior.

Orphaned rotation entries

To avoid becoming clogged with persistent errors, Vault Enterprise marks a rotation entry as orphaned if it exceeds the maximum retry limits in the associated rotation policy. Orphaning a rotation entry halts all further automated rotation attempts for the associated credential.

Restoring an orphaned rotation entry requires manual intervention:

1. Resolve any underlying errors that caused Vault to orphan the credential.
2. Update the credential to reassign the rotation policy and re-register the entry with Vault. You can use the same original configuration command to reregister the entry without changing the other configuration data.

For example, to reregister credentials for the alice role, you can reuse the previous command:

vault write ldap/static-role/alice \
    dn="cn=alice,ou=users,dc=example,dc=com" \
    username="alice" \
    rotation_period="24h" \
    rotation_policy="custom-ldap-policy"

You can check for orphans using the sys/rotation-orphans endpoint.

API

Refer to the rotation policies API documentation for more detailed information regarding management of rotation policies.