Create a dynamic MongoDB secret

A shared MongoDB password lives in every app that uses it, and changing it means changing it everywhere at once. A dynamic secret replaces it with a user of its own for each machine: your Burrow creates it in MongoDB the moment a machine reads the secret, with only the roles you choose, and drops it when its time is up.

What you need#

• A MongoDB server your Burrow can reach, and a role in your Burrow that can write secrets. For a replica set, the address of its primary.

• An admin user that can manage users on the database, ideally one made for your Burrow.

• Machines with access to the environment the secret goes in. This guide uses api's prod.

Open a new dynamic secret#

Open the environment in Projects, select the + at the top right of the secrets table and choose Dynamic. The dialog has three steps: Connection, Lease & credential, and Review.

Connect to your database#

Name the secret, such as MONGODB. Machines read it as api/prod/MONGODB, like any other secret. Set Provider to MongoDB.

Then fill in where MongoDB is and how your Burrow signs in to it:

• Host and Port: where your Burrow reaches MongoDB, 27017 by default. Your Burrow connects to this one host and no other, so for a replica set, enter its primary.

• Database: the database each machine's user is created in. It's also the database the user signs in against.

• Admin user and Admin password: the user your Burrow signs in as to create and drop each machine's user. It never leaves your Burrow, and machines never see it.

Choose how the connection is protected:

With either checking option, a CA certificate field appears. If MongoDB's certificate comes from your own CA, paste that CA's certificate there. A managed database's certificate is trusted already, so leave it empty.

Select Test connection. Your Burrow signs in with the admin user and checks it can create users. Nothing is created in MongoDB until a machine reads the secret. Select Continue.

Shape each password#

Every user gets its own random password. Under Password, set its length, from 8 to 64, which of A to Z, a to z, 0 to 9 and symbols it uses, and whether to leave out characters that look alike, such as 0 and O. Or choose UUID. The example shows the shape; each user's real password is made when it's issued.

Choose each user's roles#

On MongoDB the grants are the user's roles, one per line. A role on its own, such as readWrite, is in the secret's database; read@reporting names one in another. Without any, a user can sign in but can't read or write anything. Select Build to choose them from a list:

• Access: Read-only reads documents, Read / write also changes them, and Full manages collections and indexes too.

• Roles: tick roles one by one instead, on this database, on every database, or for monitoring the server. Any mix that isn't a preset is marked Custom.

• Scope: the database the roles apply to. They cover every collection in it, including ones created later.

The roles show as you choose. Use these grants puts them in the grants box. Read / write on app writes one:

readWrite@app

Then select Test the grants. Your Burrow creates a throwaway user with the roles and drops it again, so a role that doesn't exist shows up now rather than when a machine reads. Anything that isn't a role or role@database is refused before it reaches MongoDB.

Set the lease policy#

The lease policy decides how each user lives. A new secret starts with sensible defaults, so you may not need to change any of them:

MongoDB can't expire a user at a set time, so your Burrow drops each user when its lease ends. That's why there's no Database expiry setting for MongoDB.

Review and create#

Select Continue to see everything on one page, then Create dynamic secret. The admin password and CA certificate are saved with the secret, encrypted like any other value.

Read it from a machine#

A machine reads a dynamic secret the way it reads a structured one, and gets its own user as fields: host, port, database, sslmode, sslrootcert when you gave a CA, username and password. Use database as the connection's authSource. The username starts with rk_ and names the machine and the secret, and each user is tagged issuedBy: RatelKey Burrow in its custom data, so you can pick them out in MongoDB.

ratel run sets one variable per field, so MONGODB gives MONGODB_HOST, MONGODB_USERNAME, MONGODB_PASSWORD and so on:

ratel run --env api/prod -- ./server

A machine keeps its user across reads until it ends, and the secret's row counts the logins out. With ratel run --watch, the command restarts when its user gets a new password; a renewal keeps the password, so it restarts nothing.

Change it later#

Choose Configure from the secret's row menu. Each tab saves on its own:

The connection and roles are kept as the secret's value, so Version History lists every change, and reverting to an earlier one replaces the users like any other change.

See and revoke logins#

Choose Logins from the row menu to see every user out: the machine holding it, its username, its state, and when it was issued and ends.

The bin at the end of a row revokes that user now. Your Burrow drops it from MongoDB, then ends its open sessions where the admin user may. Its machine gets a new user on its next read.

If a user isn't issued#

Every option in one place: Dynamic secrets in the documentation.