HashiCorp Vault Dynamic Database Credentials: Architecture Note

Problem Statement

Many applications still store static database passwords in code or configuration files. This approach violates the principle of least privilege, makes rotation painful, and creates audit gaps. HashiCorp Vault’s database secrets engine can issue per‑role, short‑lived credentials that expire automatically, eliminating the need to store long‑term secrets.

Requirements

• Application must be able to authenticate to Vault (e.g., via AppRole, Kubernetes auth, or Vault Agent).
• Vault must have the database secrets engine enabled and configured for the target database (PostgreSQL, MySQL, etc.).
• Database must support dynamic user creation and revocation (most modern RDBMS do).
• Audit device enabled to capture credential generation events.
• Network path: App → Vault, Vault → DB must be reachable and secured.

Minimal Design

The smallest viable architecture creates one Vault database engine, one role, and a policy that grants the application only the read capability on the role endpoint. The application then requests credentials via the Vault API or a Vault Agent.

1. Enable the PostgreSQL secrets engine

# Run on the machine running Vault (root or vault user)
vault secrets enable -path=database database

2. Configure the database connection

vault write database/config/postgres-connection \
  plugin_name=postgresql-database-plugin \
  allowed_roles="*" \
  connection_url="postgresql://{{username}}:{{password}}@db-host:5432/postgres?sslmode=disable" \
  username="vaultadmin" \
  password="vaultadminpw"

Replace vaultadmin and vaultadminpw with a database user that has CREATE USER and DROP USER privileges. Store the credentials in Vault; they are encrypted at rest.

3. Create a role with creation and revocation SQL

vault write database/roles/app-db-role \
  db_name=postgres-connection \
  creation_statements="CREATE ROLE "{{name}}" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO "{{name}}";" \
  revocation_statements="DROP ROLE IF EXISTS "{{name}}";" \
  default_ttl="1h" \
  max_ttl="4h"

The placeholders {{name}}, {{password}}, and {{expiration}} are substituted by Vault. The default_ttl and max_ttl set the lease lifetime.

4. Define a policy for the application

cat <

5. Authenticate the application

Use AppRole or another auth method to obtain a token that is bound to app-db-policy. The token should have a short TTL (e.g., 1 hour) to limit exposure.

Trust and Data Boundaries

• Vault holds the root database credential (encrypted in its seal). It never exposes this credential to the application.
• The application receives only the short‑lived database user and password, scoped to the role’s permissions.
• All traffic between the application, Vault, and the database should be encrypted (TLS). Network segmentation can enforce that only Vault can reach the database’s admin port.
• Audit logs capture every database/creds request, providing traceability.

Operational Checks

• Lease metrics: vault metric vault.expire.num_leases shows active leases.
• Audit log: Verify entries for database/creds/app-db-role requests and responses.
• Database user count: Periodically query SELECT rolname FROM pg_roles WHERE rolname LIKE 'vault_%'; to confirm that revoked users are removed.
• Seal status: vault status should show sealed: false and initialized: true.
• Rotate the root database credential via vault write database/rotate-root on a schedule (e.g., quarterly).
• Ensure the lease-renewal daemon is running; Vault automatically renews leases that are marked renewable.

Failure Modes and Mitigations

• Vault unsealed but DB unreachable – Credential requests fail. The application should retry with exponential backoff and fall back to a cached credential if a Vault Agent is used.
• Lease renewal fails – The application must re‑authenticate to Vault and request new credentials. Vault Agent can handle this automatically.
• Revocation failure – If the DROP ROLE statement fails, orphaned DB users may remain. Use DROP ROLE IF EXISTS and monitor the database user count.
• Network partition between App and Vault – Credential fetch fails. Vault Agent with auto_auth can cache credentials and retry once connectivity is restored.
• Compromised application token – The token should have a short TTL and minimal capabilities. Implement token revocation on suspicious activity.

When to Change the Design

• High‑frequency credential requests (thousands per second) may overwhelm a single Vault server. Consider Vault Enterprise namespaces or a replicated deployment.
• Multi‑cloud database access – If the application needs credentials for databases in different clouds, enable separate database engines or configure a single engine with multiple db_name entries.
• Hardware‑backed root credential storage – If compliance requires an HSM, configure Vault’s seal to use awskms, azurekeyvault, or tpm2 and update the rotate-root schedule accordingly.
• Shift to Kubernetes – Replace direct API calls with the Vault Agent Injector to automatically inject credentials as environment variables or secrets.
• Longer lease lifetimes needed – Increase default_ttl and max_ttl in the role definition, but monitor for orphaned users and adjust revocation SQL if necessary.

Practical Verification Steps

1. Start a Vault dev server: vault server -dev.
2. Enable and configure the database engine as shown above.
3. Create a role and policy.
4. Authenticate with a token bound to the policy.
5. Request credentials: vault read database/creds/app-db-role – verify the response contains lease_id, lease_duration, and data.password.
6. Query the database to confirm the user exists: SELECT rolname FROM pg_roles WHERE rolname = 'vault_XXXX';
7. Wait for the lease to expire (or set a short TTL) and confirm the user is dropped.
8. Check Vault metrics: vault read sys/metrics?format=json | jq '.metrics.vault.expire.num_leases'.
9. Review the audit log for the credential request entry.

Conclusion

Vault’s dynamic database credentials provide a lightweight, auditable, and secure way to manage database access for applications. By following the minimal design and maintaining the operational checks outlined above, teams can eliminate static passwords and reduce the attack surface. Adjust the architecture when scaling, expanding to multi‑cloud, or meeting stricter compliance requirements.