Username templating

14min
|
Vault

Challenge

Some of Vault's secrets engines generate usernames and passwords for an external system to provide short-lived credentials to secure the target system, such as databases.

The User Configurable Password Generation for Secret Engines tutorial demonstrated the use of the password policy to set a rule for the password that an organization must adhere to (e.g. the character length of the password).

Similarly, an organization may have a username convention or standard that differs from what Vault generates by default.

Solution

Username templating lets you customize how usernames are generated for the external systems when using Vault's secrets engines. It defines the format with static text, secrets engine metadata, system information, and randomized values.

Secrets engines with support for username templating:

Requires Vault 1.7 or later	Requires Vault 1.8 or later
Cassandra	Elasticsearch
Couchbase	InfluxDB
MongoDB	MongoDB Atlas
MSSQL	RedShift
MySQL/MariaDB	SnowflakeDB
LDAP	RabbitMQ
PostgreSQL

Prerequisites

This lab was tested on macOS using an x86_64 based processor. If you are running macOS on an Apple silicon-based processor, use a x86_64 based Linux virtual machine in your preferred cloud provider.

To perform the tasks described in this tutorial, you need to have:

A Vault environment of version 1.7 or later. Refer to the Vault install guide to install Vault. Make sure that your Vault server has been initialized and unsealed.
Docker
ngrok installed and configured with auth token (HCP Vault Dedicated only)

Lab setup

Start Postgres

The tutorial requires a Postgres database. Docker provides a Postgres server image that satisfies this requirement.

Open a new terminal and pull a Postgres server image with docker.
```
$ docker pull postgres:latest
```

Create a Postgres database with a root user named root with the password rootpassword.

$ docker run \
      --name postgres \
      --env POSTGRES_USER=root \
      --env POSTGRES_PASSWORD=rootpassword \
      --detach  \
      --publish 5432:5432 \
      postgres

The database is available.

In a another terminal, connect to the Postgres database via the CLI within the postgres container.
```
$ docker exec -it postgres psql
```
Your system prompt is replaced with a new prompt root=#. Commands issued at this prompt are executed against the Postgres database running within the container.

Create a role named ro.

$ CREATE ROLE ro NOINHERIT;
CREATE ROLE

Grant the ability to read all tables to the role named ro.
```
$ GRANT SELECT ON ALL TABLES IN SCHEMA public TO "ro";
GRANT
```
The role is created and assigned the appropriate permissions.
Disconnect from the Postgres database.
```
$ \q
```

Start Vault

In a new terminal start a Vault dev server with root as the root token.
```
$ vault server -dev -dev-root-token-id root
```
The Vault dev server defaults to running at 127.0.0.1:8200. The server is initialized and unsealed.
Insecure operation
Do not run a Vault dev server in production. This approach starts a Vault server with an in-memory database and runs in an insecure way.
In a new terminal export an environment variable for the vault CLI to address the Vault server.
```
$ export VAULT_ADDR=http://127.0.0.1:8200
```
Export an environment variable for the vault CLI to authenticate with the Vault server.
```
$ export VAULT_TOKEN=root
```
The Vault server is ready.
Note
For these tasks, you can use Vault's root token. However, it is recommended that root tokens are only used for enough initial setup or in emergencies. As a best practice, use an authentication method or token that meets the policy requirements.
Set an environment variable for the PostreSQL address.
```
$ export POSTGRES_URL=127.0.0.1:5432
```

You are ready to proceed with the lab.

Note

If you do not have access to an HCP Vault Dedicated cluster, visit the Create a Vault Cluster on HCP tutorial.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copied address.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft
...snipped...

The Vault Dedicated server is ready.

For Vault Dedicated to interact with resources running on your local machine, a tunnel needs to be established.

In another terminal, start ngrok and connect to PostgreSQL.

$ ngrok tcp 127.0.0.1:5432

Example output:

ngrok                                                                                                                                                              (Ctrl+C to quit)

Session Status                online
Account                       username (Plan: Free)
Update                        update available (version 3.0.5, Ctrl-U to update)
Version                       3.0.3
Region                        United States (us)
Latency                       32.791235ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    tcp://d12b-34-567-89-10.ngrok.io:12345 -> 127.0.0.1:5432

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Copy the ngrok forwarding address.
Return to the terminal where you set the VAULT_ADDR environment variable and set an environment variable for the ngrok address. Do not include tcp://.
```
$ export POSTGRES_URL=<actual-address-from-ngrok>
```

You are ready to proceed with the lab.

Enable and configure the database secrets engine

The database secrets engine generates database credentials dynamically based on configured roles.

Enable the database secrets engine at the database/ path.
```
$ vault secrets enable database
```

Configure the database secrets engine with the connection credentials for the Postgres database.

$ vault write database/config/postgresql \
     plugin_name=postgresql-database-plugin \
     connection_url="postgresql://{{username}}:{{password}}@localhost:5432/postgres?sslmode=disable" \
     allowed_roles=readonly \
     username="root" \
     password="rootpassword"

Define the SQL used to create credentials.

$ tee readonly.sql <<EOF
CREATE ROLE "{{name}}" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}' INHERIT;
GRANT ro TO "{{name}}";
EOF

Create the role named readonly that creates credentials with the readonly.sql.

$ vault write database/roles/readonly \
      db_name=postgresql \
      creation_statements=@readonly.sql \
      default_ttl=1h \
      max_ttl=24h

Enable the database secrets engine at the database/ path.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request POST \
       --data '{"type":"database"}' \
       $VAULT_ADDR/v1/sys/mounts/database

Create an API request payload with the database configuration.

$ tee payload.json <<EOF
{
    "plugin_name": "postgresql-database-plugin",
    "connection_url": "postgresql://{{username}}:{{password}}@$POSTGRES_URL/postgres?sslmode=disable",
    "allowed_roles": "readonly",
    "username": "root",
    "password": "rootpassword"
}
EOF

Configure the database secrets engine with the connection credentials for the Postgres database.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" --request POST \
     --data @payload.json \
     $VAULT_ADDR/v1/database/config/postgresql

Create an API request payload containing the database role definition.
Note
Important: when you define the role in a production deployment, you must create user creation_statements, revocation_statements, renew_statements, and rotation_statements which are valid for the database you've configured. If you do not specify statements appropriate to creating, revoking, or rotating users, Vault inserts generic statements which can be unsuitable for your deployment.
```
$ tee payload.json <<EOF
{
    "db_name": "postgresql",
    "creation_statements": [
    "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}' INHERIT;",
    "GRANT ro TO \"{{name}}\";"
  ],
    "default_ttl": "1h",
    "max_ttl": "24h"
}
EOF
```

Create the role named readonly that creates credentials with the creation_statements defined in the payload.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request POST --data @payload.json \
       $VAULT_ADDR/v1/database/roles/readonly

Enable the database secrets engine at the database/ path.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"type":"database"}' \
   $VAULT_ADDR/v1/sys/mounts/database

Create an API request payload with the database configuration.

$ tee payload.json <<EOF
{
    "plugin_name": "postgresql-database-plugin",
    "connection_url": "postgresql://{{username}}:{{password}}@$POSTGRES_URL/postgres?sslmode=disable",
    "allowed_roles": "readonly",
    "username": "root",
    "password": "rootpassword"
}
EOF

Configure the database secrets engine with the connection credentials for the Postgres database.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" --request POST \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --data @payload.json \
   $VAULT_ADDR/v1/database/config/postgresql

Create an API request payload containing the database role definition.

$ tee payload.json <<EOF
{
    "db_name": "postgresql",
    "creation_statements": [
    "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}' INHERIT;",
    "GRANT ro TO \"{{name}}\";"
  ],
    "default_ttl": "1h",
    "max_ttl": "24h"
}
EOF

Create the role named readonly that creates credentials with the creation_statements defined in the payload.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST --data @payload.json \
   $VAULT_ADDR/v1/database/roles/readonly

Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui) and then login.
Navigate to Secrets and click Enable new engine.
From the Enable a Secrets Engine page Infra section, select Databases and click Next.
Leave all fields as-is, and click Enable Engine.
Note
This tutorial assumes that you enabled the database secrets engine at database. If yours is enabled at a different path, be sure to use the correct path as you follow this tutorial.
The database secrets engine is enabled, but there is not yet an available connection from Vault to the database. Create the connection from Vault to the PostgreSQL server by clicking Create connection.
For Database plugin, select PostgreSQL.
For Connection name, enter postgresql.
For Connection url, enter postgresql://{{username}}:{{password}}@localhost:5432/postgres?sslmode=disable.
Note
If you are configuring HCP Vault Dedicated, use the ngrok address instead of localhost:5432.
Uncheck Connection will be verified.
For Username, enter root.
For Password, enter rootpassword.
Click Create database.
When prompted to rotate the root credentials, click Rotate and enable.

The databaes secrets engine is configured and the role is defined with the default username template.

Note

Learn more about managing database credentials in Dynamic Secrets: Database Secrets Engine tutorial.

Request credentials with default username

The applications that require the database credentials read them from the secret engine's readonly role. The database secrets engines generate usernames that adhere to a default pattern.

Read credentials from the readonly database role.

$ vault read database/creds/readonly
Key                Value
---                -----
lease_id           database/creds/readonly/ZxoKlbklsliYA4hZs7umoPIz
lease_duration     1h
lease_renewable    true
password           9MSegMz7N1Fr69ZTyb#D
username           v-token-readonly-wGLPkpDyc6AgqBfMZTD3-1604195404

Read credentials from the readonly database role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request GET \
       $VAULT_ADDR/v1/database/creds/readonly | jq

Read credentials from the readonly database role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request GET \
   $VAULT_ADDR/v1/database/creds/readonly | jq

The generated username uses the default pattern expressed as a Go template:

{{printf "v-%s-%s-%s-%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 63 }}

The printf "v-%s-%s-%s-%s" function accepts text, or string, as a parameter. This string may contain text (v- and -) and variables (%s). These variables represent functions or values that return a string. These functions or values immediately follow this string.

The (.DisplayName | truncate 8) renders the .DisplayName attribute of the authenticated token. The result is then piped to the truncate function and the string is truncated, or shortened to 8 characters.

The (.RoleName | truncate 8) renders the name of the requested database secrets engine role, .RoleName, truncated again to 8 characters.

The (random 20) renders a randomized sequence of 20 lowercase letters, uppercase letters, and numbers.

The unix_time renders the current unix timestamp (number of seconds since Jan 1, 1970).

The resulting string that printf "v-%s-%s-%s-%s" produces is piped to the truncate function and truncated, or shortened to 63 characters.

Refer to the Username Templating documentation to learn more functions that can be applied.

Set the username template

A customized username template may be provided to meet the needs of your organization.

Ensure that custom username templates include enough randomness to prevent the same username being generated multiple times.

The generated username uses the default pattern expressed as a Go template:

myorg-{{.RoleName}}-{{unix_time}}-{{random 8}}

This username template is prefixed with myorg-, uses the name of role, readonly, the unix timestamp in seconds, and a random sequence of 8 characters. These functions and values are displayed inline and escaped with the {{ }} sequence.

Configure the database secrets engine with a new username template.

$ vault write database/config/postgresql \
    username_template="myorg-{{.RoleName}}-{{unix_time}}-{{random 8}}"

Read credentials from the readonly database role.

$ vault read database/creds/readonly
Key                Value
---                -----
lease_id           database/creds/readonly/NOCGtSbz7g4FFjcztX6Bqh3S
lease_duration     1h
lease_renewable    true
password           -h3B-JteYjgOPYIC6dGQ
username           myorg-readonly-1616447348-af9eHMWD

Create an API request payload with the database configuration with a new username template.

$ tee payload.json <<EOF
{
    "plugin_name": "postgresql-database-plugin",
    "connection_url": "postgresql://{{username}}:{{password}}@$POSTGRES_URL/postgres?sslmode=disable",
    "allowed_roles": "readonly",
    "username": "root",
    "password": "rootpassword",
    "username_template": "myorg-{{.RoleName}}-{{unix_time}}-{{random 8}}"
}
EOF

Re-configure the database secrets engine with the connection credentials for the Postgres database.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" --request POST \
     --data @payload.json \
     $VAULT_ADDR/v1/database/config/postgresql

Read credentials from the readonly database role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request GET \
       $VAULT_ADDR/v1/database/creds/readonly | jq

Create an API request payload with the database configuration with a new username template.

$ tee payload.json <<EOF
{
    "plugin_name": "postgresql-database-plugin",
    "connection_url": "postgresql://{{username}}:{{password}}@$POSTGRES_URL/postgres?sslmode=disable",
    "allowed_roles": "readonly",
    "username": "root",
    "password": "rootpassword",
    "username_template": "myorg-{{.RoleName}}-{{unix_time}}-{{random 8}}"
}
EOF

Re-configure the database secrets engine with the connection credentials for the Postgres database.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --data @payload.json \
   --request POST \
   $VAULT_ADDR/v1/database/config/postgresql

Read credentials from the readonly database role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request GET \
   $VAULT_ADDR/v1/database/creds/readonly | jq

Configure the database secrets engine with a new username template.

Navigate to Secrets → database → Connections.
Click the ellipsis for the row that represents your database connection name to reveal a menu.
Click Edit connection.
Within the connection edit page, click Edit configuration.
Scroll to Username template and click the toggle to enable username templating.
Enter the following template code into the text field.
Click save.

Next Step

You defined a customized username template for the database secrets engine. Learn more about templating by reading the Username Templating documentation.

You generated credentials for the database secrets engine. Learn more about managing these credentials in the Dynamic Secrets: Database Secrets Engine tutorial.

Username templating is supported by other secrets engines. Learn more about defining a username template in the Database secrets engine tutorial.

Database root credential rotation

Next Collection

Data encryption