• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Database Credentials

Skip to main content
9 tutorials
  • Dynamic Secrets: Database Secrets Engine
  • Database Root Credential Rotation
  • Database Static Roles and Credential Rotation
  • Couchbase Secrets Engine
  • Database Secrets Engine with MongoDB
  • IBM Db2 Credential Management
  • User Configurable Password Generation for Secret Engines
  • Database Secrets Engine for Microsoft SQL Server on AWS RDS
  • Database Secrets Engine for Microsoft SQL Server

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Tutorials
  4. Database Credentials
  5. Database Secrets Engine with MongoDB

Database Secrets Engine with MongoDB

  • 22min

  • VaultVault

Data protection is a top priority, and database credential rotation is a critical part of any data protection initiative. When hackers attack a system, continuous credential rotation becomes necessary, and you should strive to automate the process.

Vault's database secrets engine generates database credentials dynamically based on user-defined roles. The database administrator can pre-define the time-to-live (TTL) of the database credentials to enforce its validity so that they are automatically revoked when they expire.

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

Personas

The end-to-end scenario described in this tutorial involves two personas:

  • admin with privileged permissions to configure secrets engines
  • Vault clients (users, apps, systems, etc.) read the secrets from Vault

Prerequisites

NOTE: This lab works on macOS using x86_64 based processors. If you are running macOS on an Apple silicon processor, consider using a x86_64 based Linux virtual machine in your preferred cloud provider.

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

  • Docker to run MongDB
  • Vault installed
  • jq installed
  • ngrok installed and configured with an auth token (required for HCP Vault)

Lab setup

Start MongoDB

The tutorial requires a MongoDB database. Docker provides a MongoDB server image that you will use in this lab.

NOTE: This tutorial also works for an existing MongoDB database given appropriate credentials and connection information.

  1. Create a MongoDB database with a root user named mdbadmin with the password hQ97T9JJKZoqnFn2NXE.

    $ docker run -d \
        -p 0.0.0.0:27017:27017 -p 0.0.0.0:28017:28017 \
        --name=mongodb \
        -e MONGO_INITDB_ROOT_USERNAME="mdbadmin" \
        -e MONGO_INITDB_ROOT_PASSWORD="hQ97T9JJKZoqnFn2NXE" \
        mongo
    

The database is now available to experiment with the database secrets engine.

Start Vault

  1. In another 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.

  2. Export an environment variable for the vault CLI to address the Vault server.

    $ export VAULT_ADDR=http://127.0.0.1:8200
    
  3. Login with the root token.

    $ vault login root
    
    Success! You are now authenticated. The token information displayed below
    is already stored in the token helper. You do NOT need to run "vault login"
    again. Future Vault requests will automatically use this token.
    
    Key                  Value
    ---                  -----
    token                root
    token_accessor       n9CYvD0GK3iV6nwAOZQAy9Md
    token_duration       ∞
    token_renewable      false
    token_policies       ["root"]
    identity_policies    []
    policies             ["root"]
    

    NOTE: For these tasks, you can use Vault's root token. That said, you should use root tokens primarily for initial setup or in emergencies. As a best practice, use an authentication method or token that meets the policy requirements.

  4. Export an environment variable for the root token.

    $ export VAULT_TOKEN=root
    
  5. Export an environment variable for the MongoDB address.

    $ export MONGODB_URL=127.0.0.1:27017
    

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

  1. Launch the HCP Portal and login.

  2. Click Vault in the left navigation pane.

  3. In the Vault clusters pane, click vault-cluster.

  4. Under Cluster URLs, click Public Cluster URL. Public Cluster URL

  5. In a terminal, set the VAULT_ADDR environment variable to the copied address.

    $ export VAULT_ADDR=<Public_Cluster_URL>
    
  6. Return to the Overview page and click Generate token. Generate a Token

    Vault generates a new token.

  7. Copy the Admin Token. Generated Token

  8. Return to the terminal and set the VAULT_TOKEN environment variable.

    $ export VAULT_TOKEN=<token>
    
  9. 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.

  10. 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...
    

    You must establish a tunnel for HCP Vault to interact with resources running on your local machine.

  11. In another terminal, start ngrok and connect to postgreSQL.

    $ ngrok tcp 127.0.0.1:27017
    

    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:28017
    
    Connections                   ttl     opn     rt1     rt5     p50     p90
                                  0       0       0.00    0.00    0.00    0.00
    
  12. Copy the ngrok forwarding address.

  13. 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 MONGODB_URL=<actual-address-from-ngrok>
    

You are ready to proceed with the tutorial.

Scenario introduction

Scenario

In this tutorial, you will configure the MongoDB secrets engine and create a "tester" role that has read and write permissions.

  1. Enable the database secrets engine - admin task
  2. Configure MongoDB secrets engine - admin task
  3. Create a role - admin task
  4. Request MongoDB credentials - Vault clients to perform

This tutorial is running Vault in development mode, and use the root token. Be sure to read the Policy requirements section at the end.

Enable the database secrets engine

(Persona: admin)

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

  1. Open a web browser and launch the Vault UI (the address is the same as VAULT_ADDR).

  2. Enter the token in the Token field and click Sign In (the token is the same as VAULT_TOKEN).

  3. Select Enable new engine.

  4. Select Databases from the list, and then click Next. Enabling database

  5. Enter mongodb in the Path field. Mount path

  6. Click Enable Engine to complete.

Enable the database secrets engine at the mongodb/ path.

$ vault secrets enable -path=mongodb database

Enable the database secrets engine at the mongodb/ path.

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

Enable the database secrets engine at the mongodb/ path.

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

You enabled the database secrets engine at mongodb/.

Configure MongoDB secrets engine

(Persona: admin)

The database secrets engine supports popular databases through a plugin interface. To use a MongoDB database with the secrets engine requires further configuration with the mongodb-database-plugin plugin, and connection information.

  1. Select Create connection in the Connections tab for mongodb. Connect DB

  2. Select MongoDB from the Database plugin drop-down list.

  3. Enter mongo-test in the Connection Name field.

  4. Enter the following in the Connection URL field replacing <host:port> with the value from the MONGODB_URL environment variable.

    mongodb://{{username}}:{{password}}@<host:port>/admin?tls=false
    
  5. Enter mdbadmin in the Username and hQ97T9JJKZoqnFn2NXE in the Password text fields. Configuration

  6. Click Create database.

  7. When prompted, click Enable without rotating to continue. Root credential rotation

    This is an optional step; you should rotate the root user's password in production use. The rest of this tutorial relies on the password you set when staring the MongoDB container, so you should skip this step to complete the tutorial.

    Read the Database Root Credential Rotation tutorial to learn about rotating the root credential after the initial configuration of each database.

  8. Select mongodb. Configuration

  9. Select the Overview tab. Overview Once you set up a database connection, the overview page displays the current configuration summary.

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

$ vault write mongodb/config/mongo-test \
      plugin_name=mongodb-database-plugin \
      allowed_roles="tester" \
      connection_url="mongodb://{{username}}:{{password}}@$MONGODB_URL/admin?tls=false" \
      username="mdbadmin" \
      password="hQ97T9JJKZoqnFn2NXE"

Read the Database Root Credential Rotation tutorial to learn about rotating the root credential after the initial configuration of each database.

  1. Create an API request payload with the database configuration.

    $ tee payload.json <<EOF
    {
      "plugin_name": "mongodb-database-plugin",
      "allowed_roles": "tester",
      "connection_url": "mongodb://{{username}}:{{password}}@$MONGODB_URL/admin?tls=false",
      "username": "mdbadmin",
      "password": "hQ97T9JJKZoqnFn2NXE"
    }
    EOF
    
  2. Configure the database secrets engine with the connection credentials for the MongoDB database.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --request POST \
        --data @payload.json \
        $VAULT_ADDR/v1/mongodb/config/mongo-test
    
  1. Create an API request payload with the database configuration.

    $ tee payload.json <<EOF
    {
      "plugin_name": "mongodb-database-plugin",
      "allowed_roles": "tester",
      "connection_url": "mongodb://{{username}}:{{password}}@$MONGODB_URL/admin?tls=false",
      "username": "mdbadmin",
      "password": "hQ97T9JJKZoqnFn2NXE"
    }
    EOF
    
  2. Configure the database secrets engine with the connection credentials for the MongoDB database.

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

Read the Database Root Credential Rotation tutorial to learn about rotating the root credential after the initial configuration of each database.

The Vault generated password has a default pattern which may not adhere to your organization's password requirements. Read the User Configurable Password Generation for Secret Engines tutorial to learn about configuring the Vault-generated database password schema.

Create a role

(Persona: admin)

A role is a logical name within Vault that maps to database credentials. Some applications may just need read permissions, and others may require read and write permissions. Practice the principle of least privilege and create a role appropriately for each database client.

In this step, you will create a "tester" role with time-to-live (TTL) set to 1 hour, and the maximum TTL is 24 hours. This allows Vault to revoke the credentials automatically once they reach the TTL.

  1. In the mongodb overview page, select Create new. Overview

  2. Enter tester in the Role name field.

  3. Enter mongo-test in the Database name field.

  4. Select dynamic from the Type of role drop-down list.

    Read the Database Static Roles and Credential Rotation tutorial to learn about static roles.

  5. Verify Generated credential's Time-to-Live (TTL) and Generated credential's maximum Time-to-Live (Max TTL) is to set the value to 1 hour and 1 day respectively.

  6. Enter the following in the Creation statement field.

    {
      "db": "admin",
      "roles": [
        {
          "role": "readWrite"
        },
        {
          "role": "read",
          "db": "foo"
        }
      ]
    }
    

    The Create Role page should look as below: Create a Role

  7. Click Create Role to complete.

  1. Create the role named tester.

    $ vault write mongodb/roles/tester \
        db_name=mongo-test \
        creation_statements='{ "db": "admin", "roles": [{ "role": "readWrite" }, {"role": "read", "db": "foo"}] }' \
        default_ttl="1h" \
        max_ttl="24h"
    
  2. Verify that the tester role exists.

    $ vault list mongodb/roles
    
    Keys
    ----
    tester
    
  1. Create an API request payload containing the database role definition.

    $ tee payload-role.json <<EOF
    {
        "db_name": "mongo-test",
        "creation_statements": [
        "{ \"db\": \"admin\", \"roles\": [{ \"role\": \"readWrite\" }, {\"role\": \"read\", \"db\": \"foo\"}] }"
        ],
        "default_ttl": "1h",
        "max_ttl": "24h"
    }
    EOF
    
  2. Create the role named tester that creates credentials with the creation_statements defined in the payload.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
           --request POST --data @payload-role.json \
           $VAULT_ADDR/v1/mongodb/roles/tester
    
  1. Create an API request payload containing the database role definition.

    $ tee payload-role.json <<EOF
    {
        "db_name": "mongo-test",
        "creation_statements": [
        "{ \"db\": \"admin\", \"roles\": [{ \"role\": \"readWrite\" }, {\"role\": \"read\", \"db\": \"foo\"}] }"
        ],
        "default_ttl": "1h",
        "max_ttl": "24h"
    }
    EOF
    
  2. Create the role named tester 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-role.json \
        $VAULT_ADDR/v1/mongodb/roles/tester
    

Vault can now dynamically generate database credentials useful for connecting to the mongodb database.

Request MongoDB credentials

(Persona: Vault clients)

To connect to the MongoDB, Vault clients request Vault to dynamically generate the database credentials based on its role. In this case, the tester role.

This step uses the root token for demonstration. In reality, Vault clients would never use Vault's root token. After learning the basic steps, continue onto the Policy requirements section.

  1. Return to the mongo-test configuration page by selecting mongodb > mongo-test.

  2. Select the tester role. Allowed roles

  3. Select Generate credentials. Generate credentials

    This presents the generated lease. Click on the copy to clipboard icon to copy the generated username and password. Credentials

NOTE: From the mongodb overview page, enter the role name in the Get Credentials field and click Get Credentials to do the same. The Get Credentials works for any role configured on the mongodb.

Credentials

Read credentials from the tester database role.

$ vault read mongodb/creds/tester

Example output:

Key                Value
---                -----
lease_id           mongodb/creds/tester/fyF5xDomnKeCHNZNQgStwBKD
lease_duration     1h
lease_renewable    true
password           A1a-ckirtymYaXACpIHn
username           v-token-tester-6iRIcGv8tLpu816oblPY-1556567086

Read credentials from the tester database role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
       --request GET \
       $VAULT_ADDR/v1/mongodb/creds/tester | jq .data

NOTE: This example uses jq to process the JSON output for readability.

Example output:

{
  "password": "tHjmYnh7vb7zIXkuE-UU",
  "username": "v-token-tester-VX26utiXIlrseoBbgZuz-1615452504"
}

Read credentials from the tester database role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
    --request GET \
    $VAULT_ADDR/v1/mongodb/creds/tester | jq .data

NOTE: This example uses jq to process the JSON output for readability.

Example output:

{
  "password": "tHjmYnh7vb7zIXkuE-UU",
  "username": "v-token-tester-VX26utiXIlrseoBbgZuz-1615452504"
}

The MongoDB credentials are a username and a password. Vault identifies the credentials by their lease ID.

Read the customize the generated username schema section for additional discussion.

Validation

Connect to the MongoDB database using the Vault generated credentials.

$ docker exec -it mongodb mongosh --username <username> --password <password>

Example:

$ docker exec -it mongodb mongosh \
    --username v-token-tester-fO7smPyTgCrySIgQNrst-1615451034 \
    --password IePqQ26-EyIk6zEA637w

MongoDB shell version v4.4.4
connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb
Implicit session: session { "id" : UUID("aabf31e2-27f9-4ac5-9145-710dbd84ef8d") }
MongoDB server version: 4.4.4

You can list databases.

> show dbs;
admin  0.000GB

Enter exit to exit out of the Docker container.

Policy requirements

Each persona requires a different set of capabilities, and you use ACL policies to enforce those capabilities. If you are not familiar with policies, complete the policies tutorial.

Example policy for admin

The admin persona needs to be able to set up the database secrets engine.

  • Enable the database secrets engine at mongodb (sys/mounts/mongodb)
  • Configure the MongoDB connection (mongodb/config/mongo-test)
  • Create a role (mongodb/roles/tester)
Admin persona

An admin needs to set up the Vault clients so they can communicate with Vault.

  • Create policies for the Vault clients (sys/policies/acl/<policy_name>)
  • Enable an auth method for the Vault clients to login with Vault (sys/auth/<auth_method>)
  • Configure the auth method (auth/<auth_method>)
# Enable secrets engines at any path
path "sys/mounts/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Manage the database secrets engine enabled at `mongodb` path
path "mongodb/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Create ACL policies for Vault clients
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

#-----------------------------------------
# Example: Use AppRole auth method
#-----------------------------------------
# Enable approle auth method at 'approle'
path "sys/auth/approle" {
  capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}

# List all enabled auth methods
path "sys/auth" {
  capabilities = [ "read", "list" ]
}

# Create and manage roles
path "auth/approle/role/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

#------------------------------------------
# Create token for testing
#------------------------------------------
# Create tokens
path "auth/token/create" {
  capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}

You should be able to complete this tutorial using a token with the above policy attached. If you are not familiar with creating policies, read the Vault Policies tutorial.

Example policy for Vault clients

The Vault clients persona needs to be able to request credentials from Vault.

Apps persona
# Required: Get credentials from the database secrets engine for 'tester' role.
path "mongodb/creds/tester" {
  capabilities = [ "read", "update"]
}

# Recommended: List all dynamic and static roles
path "mongodb/roles" {
  capabilities = [ "list" ]
}

path "mongodb/static-roles" {
  capabilities = [ "list" ]
}

Create a client policy

  1. Select Policies and then Create ACL policy.

  2. Enter clients in the Name field.

  3. Copy the policy and paste it into the Policy text box.

    # Required: Get credentials from the database secrets engine for 'tester' role.
    path "mongodb/creds/tester" {
      capabilities = [ "read", "update"]
    }
    
    # Recommended: List all dynamic and static roles
    path "mongodb/roles" {
      capabilities = [ "list" ]
    }
    
    path "mongodb/static-roles" {
      capabilities = [ "list" ]
    }
    
  4. Click Create policy.

  5. Log out of the Vault UI and switch to the terminal session you started in the Lab setup section.

  6. Create a token with the clients policy attached.

    $ vault token create -policy=clients -ttl=8h
    

    Example output:

    Key                  Value
    ---                  -----
    token                hvs.ad3DG8zxyPcqq4cvrMzsIxr9
    token_accessor       lUcfmpppZVO1Sr6f6gwXznaF
    token_duration       8h
    token_renewable      true
    token_policies       ["clients" "default"]
    identity_policies    []
    policies             ["clients" "default"]
    

    Copy the generated token value. In this example, the token is hvs.ad3DG8zxyPcqq4cvrMzsIxr9.

  7. Return to the Vault UI and enter the generated token to sign in.

  8. Select mongodb/. Credentials

  9. Under Get Credentials, enter tester in the Role to use field.

  10. Click Get Credentials to display the credentials.

  1. Create an clients policy.

    $ vault policy write clients -<<EOF
    # Required: Get credentials from the database secrets engine for 'tester' role.
    path "mongodb/creds/tester" {
      capabilities = [ "read", "update"]
    }
    
    # Recommended: List all dynamic and static roles
    path "mongodb/roles" {
      capabilities = [ "list" ]
    }
    
    path "mongodb/static-roles" {
      capabilities = [ "list" ]
    }
    EOF
    
  2. Create a token with the clients policy attached and save it as an environment variable.

    $ CLIENT_TOKEN=$(vault token create -policy=clients -ttl=8h -format=json | jq -r '.auth | .client_token')
    
  3. Verify the CLIENT_TOKEN has the clients policy attached.

    $ vault token lookup $CLIENT_TOKEN
    
    Key                 Value
    ---                 -----
    accessor            XqYk8PShzsMYvLtJY7xZgp3I.Xvmlx
    creation_time       1658500884
    creation_ttl        8h
    display_name        token
    entity_id           bfa78daa-8b65-1f5f-1167-7768b68a68bc
    expire_time         2022-07-22T22:41:24.092104544Z
    explicit_max_ttl    0s
    id                  hvs.CAESIC4h7k8Yc7hawkem_oEDBmJg7pNv3jWgc5qRq_FoDJ1oGicKImh2cy5Ja1hKMEdpTXEyVnc4OWkyWTNCOHpmS0QuWHZtbHgQ1QM
    issue_time          2022-07-22T14:41:24.092141504Z
    meta                <nil>
    namespace_path      admin/
    num_uses            0
    orphan              false
    path                auth/token/create
    policies            [clients default]
    renewable           true
    ttl                 7h46m52s
    type                service
    

    Review the policies value to find the clients and default policies attached to the token.

  4. Use the CLIENT_TOKEN to request new credentials from the tester role.

    $ VAULT_TOKEN=$CLIENT_TOKEN vault read mongodb/creds/tester
    

    Vault outputs the credentials.

    Example output:

    Key                Value
    ---                -----
    lease_id           mongodb/creds/tester/Ktwvj5K0iIE05LDlGjl0391A.3EPkJ
    lease_duration     1h
    lease_renewable    true
    password           Q-E5Xggr-40mrfz3xHn5
    username           v-token-tester-IgB57Tnu3G3QylDsuXso-1658773433
    
  1. Create an API request payload containing the client policy.

    $ tee payload-policy.json <<EOF
    {"policy": "# Required: Get credentials from the database secrets engine for 'tester' role.\npath \"mongodb/creds/tester\" {\n  capabilities = [ \"read\", \"update\"]\n}\n\n# Recommended: List all dynamic and static roles\npath \"mongodb/roles\" {\n  capabilities = [ \"list\" ]\n}\n\npath \"mongodb/static-roles\" {\n  capabilities = [ \"list\" ]\n}\n"}
    EOF
    
  2. Create the clients policy defined in payload-policy.json

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --request POST --data @payload-policy.json \
        $VAULT_ADDR/v1/sys/policies/acl/clients
    
  3. Create an API request payload.

    $ tee payload-token.json <<EOF
    {"policies": "clients"}
    EOF
    
  4. Create a token with the clients policy attached and save it as an environment variable.

    $ CLIENT_TOKEN=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --request POST \
        --data @payload-token.json \
        $VAULT_ADDR/v1/auth/token/create | jq -r '.auth | .client_token')
    
  5. Create an API payload.

    $ tee payload-readtoken.json <<EOF
    {"token": "$CLIENT_TOKEN"}
    EOF
    
  6. Verify the CLIENT_TOKEN has the clients policy attached.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --request POST \
        --data @payload-readtoken.json \
        $VAULT_ADDR/v1/auth/token/lookup | jq -r '.data | .policies'
    

    Example output:

    [
      "clients",
      "default"
    ]
    
  7. Use the CLIENT_TOKEN to request new credentials from the tester role.

    curl --header "X-Vault-Token: $CLIENT_TOKEN" \
       --request GET \
       $VAULT_ADDR/v1/mongodb/creds/tester | jq -r '.data'
    

    Example output:

    {
      "password": "iZGfE64P5tcZKfUeJAt-",
      "username": "v-token-tester-xFsHwJ2A8zlBGyilddef-1658773228"
    }
    
  1. Create an API request payload containing the client policy.

    $ tee payload-policy.json <<EOF
    {"policy": "# Required: Get credentials from the database secrets engine for 'tester' role.\npath \"mongodb/creds/tester\" {\n  capabilities = [ \"read\", \"update\"]\n}\n\n# Recommended: List all dynamic and static roles\npath \"mongodb/roles\" {\n  capabilities = [ \"list\" ]\n}\n\npath \"mongodb/static-roles\" {\n  capabilities = [ \"list\" ]\n}\n"}
    EOF
    
  2. Create the clients policy defined in payload-policy.json

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
        --request POST --data @payload-policy.json \
        $VAULT_ADDR/v1/sys/policies/acl/clients
    
  3. Create an API request payload.

    $ tee payload-token.json <<EOF
    {"policies": "clients"}
    EOF
    
  4. Create a token with the clients policy attached and save it as an environment variable.

    $ CLIENT_TOKEN=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
        --request POST \
        --data @payload-token.json \
        $VAULT_ADDR/v1/auth/token/create | jq -r '.auth | .client_token')
    
  5. Create an API payload.

    $ tee payload-readtoken.json <<EOF
    {"token": "$CLIENT_TOKEN"}
    EOF
    
  6. Verify the CLIENT_TOKEN has the clients policy attached.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
        --request POST \
        --data @payload-readtoken.json \
        $VAULT_ADDR/v1/auth/token/lookup | jq -r '.data | .policies'
    

    Example output:

    [
      "clients",
      "default"
    ]
    
  7. Use the CLIENT_TOKEN to request new credentials from the tester role.

    curl --header "X-Vault-Token: $CLIENT_TOKEN" \
       --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
       --request GET \
       $VAULT_ADDR/v1/mongodb/creds/tester | jq -r '.data'
    

    Example output:

    {
      "password": "iZGfE64P5tcZKfUeJAt-",
      "username": "v-token-tester-xFsHwJ2A8zlBGyilddef-1658773228"
    }
    

Customize the generated username schema

In the request MongoDB credentials section, you saw the Vault generated username and password. The generated username resembles v-token-tester-6iRIcGv8tLpu816oblPY-1556567086. This may be less obvious to differentiate a username from another when you are auditing the database access.

Update the mongo-test connection configuration to specify that the generated database username to have the format of mongo-<role_name>-<random_char_length_8>.

In this tutorial, you created a tester role, so the <role_name> is tester.

  1. Update the mongo-test connection configuration with username template.

    $ vault write mongodb/config/mongo-test \
          plugin_name=mongodb-database-plugin \
          allowed_roles="tester" \
          connection_url="mongodb://{{username}}:{{password}}@$MONGODB_URL/admin?tls=false" \
          username="mdbadmin" \
          password="hQ97T9JJKZoqnFn2NXE" \
          username_template="mongo-test-{{.RoleName}}-{{random 8}}"
    

    The username_template parameter specifies the username format ("mongo-test-{{.RoleName}}-{{random 8}}"). The {{.RoleName}} returns the role name (tester) used to request a lease. The {{random 8}} returns 8 random characters.

  2. Request a new set of credentials.

    $ vault read mongodb/creds/tester
    

    Example output:

    Key                Value
    ---                -----
    lease_id           mongodb/creds/tester/JPQtefXthLkh7hE8vPpBY5Zw
    lease_duration     24h
    lease_renewable    true
    password           GHVxvy6gDf7zD9Kxk-8f
    username           mongo-test-tester-vLjw7VJI
    

    The generated username (mongo-test-tester-vLjw7VJI) adheres to the username template.

  1. Create the request payload to include a username template.

    $ tee payload.json <<EOF
    {
        "plugin_name": "mongodb-database-plugin",
        "allowed_roles": "tester",
        "connection_url": "mongodb://{{username}}:{{password}}@$MONGODB_URL/admin?tls=false",
        "username": "mdbadmin",
        "password": "hQ97T9JJKZoqnFn2NXE",
        "username_template": "mongo-test-{{.RoleName}}-{{random 8}}"
    }
    EOF
    

    The username_template parameter specifies the username format ("mongo-test-{{.RoleName}}-{{random 8}}"). The {{.RoleName}} returns the role name (tester) used to request a lease. The {{random 8}} returns 8 random characters.

  2. Update the mongo-test connection configuration with username template.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --request POST \
        --data @payload.json \
        $VAULT_ADDR/v1/mongodb/config/mongo-test
    
  3. Request a new set of credentials.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
           --request GET \
           $VAULT_ADDR/v1/mongodb/creds/tester | jq .data
    

    Example output:

    {
      "password": "wrcQNdea7jN2c6r1sVi-",
      "username": "mongo-test-tester-kJ1mfMqM"
    }
    

    The generated username (mongo-test-tester-kJ1mfMqM) adheres to the username template.

  1. Create the request payload to include a username template.

    $ tee payload.json <<EOF
    {
        "plugin_name": "mongodb-database-plugin",
        "allowed_roles": "tester",
        "connection_url": "mongodb://{{username}}:{{password}}@$MONGODB_URL/admin?tls=false",
        "username": "mdbadmin",
        "password": "hQ97T9JJKZoqnFn2NXE",
        "username_template": "mongo-test-{{.RoleName}}-{{random 8}}"
    }
    EOF
    

    The username_template parameter specifies the username format ("mongo-test-{{.RoleName}}-{{random 8}}"). The {{.RoleName}} returns the role name (tester) used to request a lease. The {{random 8}} returns 8 random characters.

  2. Update the mongo-test connection configuration with username template.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
        --request POST \
        --data @payload.json \
        $VAULT_ADDR/v1/mongodb/config/mongo-test
    
  3. Request a new set of credentials.

    $ curl --header "X-Vault-Token: $VAULT_TOKEN" \
        --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
        --request GET \
        $VAULT_ADDR/v1/mongodb/creds/tester | jq .data
    

    Example output:

    {
      "password": "wrcQNdea7jN2c6r1sVi-",
      "username": "mongo-test-tester-kJ1mfMqM"
    }
    

    The generated username (mongo-test-tester-kJ1mfMqM) adheres to the username template.

To customize the password rules, read the User Configurable Password Generation for Secret Engines tutorial.

Next steps

Resources are available to help integrate your applications with a Vault database secrets engine. You can use these resources, and your existing applications will require little to no code changes to work with Vault.

Refer to the following tutorials:

  • Direct Application Integration
  • Using HashiCorp Vault C# Client with .NET Core
  • Vault Agent Templates
  • Vault Agent Caching

Help and reference

  • Secrets Engines - Databases
  • Role API
  • User Configurable Password Generation for Secret Engines
  • Database Root Credential Rotation
  • Database Static Roles and Credential Rotation
 Previous
 Next

On this page

  1. Database Secrets Engine with MongoDB
  2. Personas
  3. Prerequisites
  4. Lab setup
  5. Scenario introduction
  6. Enable the database secrets engine
  7. Configure MongoDB secrets engine
  8. Create a role
  9. Request MongoDB credentials
  10. Policy requirements
  11. Customize the generated username schema
  12. Next steps
  13. Help and reference
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)