12.4 Vault Secrets: Versions, Rotation States, Automatic Generation & Rotation

Why Secrets Belong in Vault

Hardcoded passwords in source code, container images, or environment files are among the most common causes of breaches. Vault secrets keep credentials in a managed, audited store:

• A secret is encrypted with a master encryption key from a vault, and that key must be symmetric (AES).
• Secret contents are base64-encoded before they are sent to the service. The Console lets you type plain text and encodes it for you.
• Access is controlled with IAM on the secret-family resources, such as read secret-bundles for applications that only need to retrieve values, and every access is recorded by Audit.

Retrieving Secrets Without Stored Credentials

Applications should authenticate to Vault with an OCI identity rather than a stored API key:

The application calls the Secrets API at run time to read the current version, often caching it briefly.

Secret Versions and Rotation States

A secret is a container for one or more secret versions. Each version can carry one or more rotation states:

When a secret is first created, its single version is both current and latest. During rotation, a new version is added as pending, and applications keep using current until the pending version is promoted. Any version other than a deprecated one can be marked current again to roll back, and only deprecated versions can be deleted.

Automatic Secret Generation

Since February 2024, Vault can generate secrets for you, such as passwords and SSH keys, using templates that define the format, so humans never see or choose the value. The Console shows whether a secret is auto-generated and auto-rotated, and work requests let you track secret operations.

Automatic Secret Rotation

Automatic rotation changes a secret on a schedule with an interval from 1 to 12 months. It integrates with Autonomous AI Database and OCI Functions, so the new value is applied to the target system and not just stored in Vault.

The Rotation Function Contract

For a target that a function updates, Vault calls the function with the secret OCID, the current version number, and a step. The function must implement four steps:

1. VERIFY_CONNECTION: confirm the existing credentials in the secret still work against the target system.
2. CREATE_PENDING_VERSION: create a new pending secret version (or reuse an existing pending version).
3. UPDATE_TARGET_SYSTEM: change the credential on the target system to the pending value.
4. PROMOTE_PENDING_VERSION: move the pending version to current.

If a step fails, for example because the database cannot be reached during UPDATE_TARGET_SYSTEM, the pending version is never promoted. Applications keep using the unchanged current version, so a failed rotation does not lock them out.

Pre-Built Rotation Functions

Oracle provides pre-built functions in OCI Functions for database credentials: Database Secret Rotation with Wallet (mutual TLS to the database) and Database Secret Rotation without Wallet (TLS). When you create one from the Pre-Built Functions page, OCI Functions can create the dynamic group and IAM policy the function needs. You must also allow the Vault secret rotation service to invoke the function, and the database must allow network access from the function's application subnet.

Common Mistakes

• Encrypting a secret with an asymmetric key: secrets require a symmetric master encryption key.
• Giving applications manage instead of read permissions on secrets, which lets a compromised application change or delete them.
• Caching a secret value forever, so a rotated password breaks the application until it restarts.
• Rotating the value in Vault without changing it in the target system. Automatic rotation with a rotation function avoids this, because the target is updated before the new version becomes current.

Designing for Rotation

• Store one credential per secret, and point applications at the secret OCID rather than a version number.
• Make applications re-read the secret when authentication fails, so they pick up a newly promoted version.
• Use separate secrets for each environment and region, and replicate or recreate them in the DR region alongside the keys that encrypt them.
• Restrict manage secret-family to the security team, and give applications only read secret-bundles.