Difficulty: beginner
Estimated Time: 10 minutes


Data protection is a top priority, and database credential rotation is a critical part of any data protection initiative. Each role has a different set of permissions granted to access the database. When a system is attacked by hackers, continuous credential rotation becomes necessary and needs to be automated.

Applications ask Vault for database credentials rather than setting them as environment variables. The administrator specifies the TTL of the database credentials to enforce its validity so that they are automatically revoked when they are no longer used.

Each app instance can get unique credentials that they don't have to share. By making those credentials short-lived, you reduce the chance that they might be compromised. If an app was compromised, the credentials used by the app can be revoked rather than changing more global sets of credentials.

There are some tools available to help integrate your applications with Vault's database secrets engine. Using those tools, the existing applications may require minimum to no code change to work with Vault.

Refer to the following guides:

Help and Reference

Vault Dynamic Secrets - Database Secrets Engine

Step 1 of 4

Setup Database secrets engine

Login with root token.

Click on the command () will automatically copy it into the terminal and execute it.

vault login root

Run a PostgreSQL Docker image

For the purpose of this tutorial, let's run PostgreSQL Docker image in a container.

Execute the following command to start a postgres instance which listens to port 5432, and the superuser (root) password is set to rootpassword.

docker run --name postgres -e POSTGRES_USER=root \
         -e POSTGRES_PASSWORD=rootpassword \
         -d -p 5432:5432 postgres

Verify that the postgres container is running.

docker ps
CONTAINER ID        IMAGE            ...         PORTS                    NAMES
befcf913da91        postgres         ...>5432/tcp   postgres

Setup database secrets engine

Execute the following command to enable the database secrets engine at database/ path.

vault secrets enable database

The PostgreSQL secrets engine needs to be configured with valid credentials. It is very common to give Vault the superuser credentials and let Vault manage the auditing and lifecycle credentials; it's much better than having one person manage the credentials.

vault write database/config/postgresql \
    plugin_name=postgresql-database-plugin \
    allowed_roles=readonly \
    connection_url=postgresql://root:[email protected]:5432/postgres?sslmode=disable

To learn more about managing the database root credentials, refer to the Database Root Credential Rotation guide.

The next step is to define the readonly role. A role is a logical name that maps to a policy used to generate credentials. Since Vault does not know what kind of PostgreSQL users you want to create, supply the information in SQL to create desired users.

View the provided readonly.sql file:

cat readonly.sql

The values within the {{<value>}} will be filled in by Vault. Notice that VALID_UNTIL clause. This tells PostgreSQL to revoke the credentials even if Vault is offline or unable to communicate with it.

CREATE ROLE "{{name}}" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';

Execute the following command to creates a role named readonly with default TTL of 1 hour, and max TTL of the credential is set to 24 hours. The readonly.sql statement is passed as the role creation statement.

vault write database/roles/readonly db_name=postgresql \
   [email protected] \
   default_ttl=1h max_ttl=24h

Creating Katacoda Scenarios

Thanks for creating Katacoda scenarios. This tab is designed to help you as an author have quick access the information you need when creating scenarios.

This tab will not be visible to users.

Here are some useful links to get you started.

Running Katacoda Workshops

If you are planning to use Katacoda for workshops, please contact [email protected] to arrange capacity.

Debugging Scenarios

Below is the response from any background scripts run or files uploaded. This stream can aid debugging scenarios.

If you still need assistance, please contact [email protected]