Skip to content
SRE & DevOpsDeep Dive Published Updated 6 min readViews unavailable

HashiCorp Vault Database Secrets: Dynamic Users, Static-Role Rotation, and Lease Operations

Design Vault database secrets with least privilege, distinguish dynamic users from rotated static accounts, and plan lease revocation apart from live SQL sessions.

The Vault database secrets engine can create short-lived database accounts on demand and revoke them when their leases expire. It can also manage and periodically rotate the password of an existing database user through a static role. These are different lifecycle models: dynamic credentials create a distinct account per lease, while a static role maps one Vault role to one external username whose password changes over time. Picking the wrong model can cause a credential leak, an outage at rotation, or a false belief that existing database sessions are terminated when a Vault lease expires.

The engine is a broker, not a database proxy. Vault authenticates the caller, evaluates policy, and uses a configured database plugin and administrative connection to create, rotate, or revoke database credentials. Applications still need secure delivery, a connection-pool refresh strategy, and a way to react when credentials expire. Vault’s database audit events are not a substitute for database-side audit logs that identify SQL activity.

Separate the administrative connection from application roles

Create a dedicated database principal for Vault rather than using the database’s human administrator or built-in superuser. Grant it only the operations needed to create, alter, and revoke the account types you will issue. Configure each database connection with an explicit allowlist of roles; this limits which Vault roles that connection can mint. Store the administrative password through a controlled provisioning path and protect the Vault path with a narrowly scoped policy.

At a high level, operators enable the database/ secrets engine, configure a plugin-specific connection, define roles, and grant callers permission to request only the intended credentials path. The exact connection URL and SQL statements depend on the database plugin and its version; do not copy a PostgreSQL example into MySQL, Oracle, or a managed database service without checking the matching plugin documentation.

vault secrets enable -path=database database

# Illustrative only: use the exact connection fields and TLS settings
# documented for your chosen database plugin. Supply administrative
# credentials through an approved protected input mechanism.
vault write database/config/orders-db \
  plugin_name="<database-plugin>" \
  connection_url="<plugin-specific-TLS-connection-url>" \
  allowed_roles="orders-readonly,orders-migrator" \
  username="<dedicated-vault-database-principal>"

Do not put a real password in a shell command, committed example, terminal transcript, or CI log. Ensure the database connection validates TLS certificates and targets the intended host. Test the administrative principal’s effective grants directly in a non-production database before enabling the secrets engine for application use.

Dynamic roles: unique account, scoped grants, expiring lease

A dynamic role contains database-specific account-creation and revocation statements plus a TTL and maximum TTL. When a caller requests database/creds/orders-readonly, Vault runs the plugin’s creation logic, returns a new username and password, and associates the credential with a lease. The database username can make attribution clearer than a shared application credential, but only if database logs retain the mapping from username to Vault request, application identity, and deployment.

Grant the generated account only the access required. A read-only service should not receive DDL or administrative privileges; a migration identity should not be available to ordinary application replicas. Check how the database applies grants to existing and future objects, whether default privileges are needed, and whether revocation can drop the generated account when ownership or dependent objects exist. Plugin statements are executable database code: validate create, rollback, renew, and revocation behavior against the actual engine.

The Vault lease controls Vault’s credential lifecycle and revocation scheduling. It does not guarantee that the database forcibly terminates every already-established session at the precise expiration time. Session behavior is database- and configuration-dependent. Test what happens to a running connection when a user is revoked, and ensure an application connection pool can replace expired credentials without taking every replica down simultaneously.

Static roles: rotate a fixed database identity deliberately

Use a static role when an existing account must remain stable for a legacy integration or when the database cannot support the desired dynamic-account workflow. A static role is a one-to-one mapping to a database username. Vault stores and rotates its password on a configured period or schedule, and permitted callers read the current password. Every consumer of that username must tolerate the same rotation event; static roles are not per-request identities and do not provide per-workload database usernames.

Never onboard Vault’s own database administrative/root connection user as a static role on the same database connection. HashiCorp warns that rotating that account through a static role invalidates the credentials Vault itself uses to manage other roles. Use the documented root-credential rotation endpoint and procedure for that separate administrative credential. Also review whether static-role import rotates a password immediately; test the onboarding/cutover behavior so an application is not surprised when its current credential stops working.

Schedule-based rotation can define a maintenance window. If rotation cannot complete before that window ends, it waits for the next scheduled occurrence. That makes monitoring and alert ownership essential: a rotation failure may leave the previous password active rather than magically fixing itself before the application’s credential expires. Alert on failed rotations and test how consumers retrieve the changed password.

Policy, delivery, and lease operations

Policies should grant only the exact database credential path the workload needs, not broad access to the entire engine. Use a distinct Vault auth identity for each service or deployment role. Issue a limited token, deliver secrets through an appropriate agent or application integration, and prevent values from entering logs, crash dumps, artifacts, shell history, or metrics labels. If a platform synchronizes Vault values into a Kubernetes Secret, account for Kubernetes RBAC, API-server encryption, namespace boundaries, and the fact that the copied value has a separate lifecycle.

For every dynamic credential, choose TTLs based on expected application session and rotation behavior, set a sensible maximum TTL, and decide whether renewal is required or should be replaced by fresh credentials. Build metrics and alerts for lease issuance, renew/revoke failures, database plugin health, Vault seal/availability, audit-device health, and connection-pool authentication errors. Do not treat vault lease revoke as a proof that application connections were closed; verify both new authentication denial and the database’s existing-session behavior.

An acceptance test should cover at least these cases in a staging database: an authorized caller obtains a read-only dynamic account; an unauthorized caller is denied; the account cannot write; expiry/revocation removes the account or otherwise denies new connections; the application survives a credential refresh; a rotation failure pages the owner; and the audit record can be correlated with database login evidence. Repeat the test after upgrading Vault or a database plugin, because plugin behavior is part of the contract.

Related:

Sources:

Comments