MongoDB database plugin HTTP API

The MongoDB database plugin is one of the supported plugins for the database secrets engine. This plugin generates database credentials dynamically based on configured roles for the MongoDB database.

Configure connection

In addition to the parameters defined by the Database Backend, this plugin has a number of parameters to further configure a connection.

Method	Path
POST	/database/config/:name

Parameters

• connection_url (string: <required>) – Specifies the MongoDB connection URI, e.g. mongodb://{{username}}:{{password}}@host:27017/admin. This field can be templated and supports passing the username and password parameters in the {{field_name}} format. A templated connection URL is required when using root credential rotation.

• username (string: <required>) – Specifies the root credential username OpenBao uses to log into MongoDB and issue/revoke dynamic users.

• password (string: <required>) – Specifies the root credential password corresponding to username.

• write_concern (string: "") – Specifies the write concern to use for user-management commands (createUser, updateUser, dropUser), as a JSON document, e.g. {"wmode":"majority","wtimeout":1000,"j":true}. May also be base64-encoded JSON — the plugin tries base64 decoding first and falls back to raw JSON. If unset, defaults to {"wmode":"majority"}.

• tls_ca (string: "") – Specifies a PEM bundle containing one or more CA certificates to use when connecting to MongoDB over TLS.

• tls_certificate_key (string: "") – Specifies a PEM-encoded certificate and private key, concatenated together, to use for client authentication. When set, the plugin authenticates as username using the MONGODB-X509 auth mechanism instead of password authentication.

• socket_timeout (string: "1m") – Specifies how long the driver waits for a socket read or write to complete before timing out.

• connect_timeout (string: "1m") – Specifies how long the driver waits when establishing a new connection before timing out.

• server_selection_timeout (string: "") – Specifies how long the driver waits when selecting a server for an operation before timing out. If unset, the underlying MongoDB driver's default is used.

• username_template (string) - Template describing how dynamic usernames are generated.

Default Username Template

{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 15) (.RoleName | truncate 15) (random 20) (unix_time) | replace "." "-" | truncate 100 }}

Example Usernames:

Example
DisplayName	token
RoleName	myrolename
Username	v-token-myrolename-uszt1n4cyhal4m0xtgx3-1614294836

Sample payload

{
  "plugin_name": "mongodb-database-plugin",
  "allowed_roles": "readonly",
  "connection_url": "mongodb://{{username}}:{{password}}@mongo.example.com:27017/admin",
  "username": "root",
  "password": "secret"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/config/my-mongo

Statements

Unlike SQL-style database plugins, MongoDB does not use semicolon-separated statement lists. Instead creation_statements (and, optionally, revocation_statements) are each a single JSON document describing the authentication database and role(s) to apply, matching the shape MongoDB's createUser command expects.

For more information on configuring roles see the Role API in the database secrets engine docs.

Parameters

The following are the statements used by this plugin. If not mentioned in this list the plugin does not support that statement type.

• creation_statements (string: <required>) – Specifies a single JSON document describing the user to create:

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

  • db (optional, defaults to "admin") is the authentication database the user is created in.
  • roles (required) is an array of MongoDB role documents. Bare role names (no db) are flattened to plain strings; db-qualified roles are passed through as objects, matching createUser's expected shape.

  There is no built-in default; a role without creation_statements fails to issue credentials.

• revocation_statements (string: "") – Specifies a single JSON document, in the same {"db": "..."} shape as creation_statements, used to determine the authentication database to run dropUser against. Only db is read; if not provided, or if db is omitted, defaults to "admin". If the user has already been removed from MongoDB, revocation is treated as successful rather than retried.

rollback_statements and rotation_statements are accepted by the database secrets engine framework but are not used by this plugin — password rotation for static roles is performed with MongoDB's updateUser command directly, not through a configurable statement.

Root credential rotation

$ bao write -force database/rotate-root/my-mongo

Rotates the root user's password (the username/password pair configured on database/config/:name) via updateUser. The old password is not recoverable afterward.

Static roles

Static roles rotate the password of an existing MongoDB user on a schedule, via updateUser:

$ bao write database/static-roles/svc \
    db_name=my-mongo \
    username=svc \
    rotation_period=24h

MongoDB has no native VALID UNTIL clause on users, so dynamic-role lease expiry is enforced by OpenBao revoking the lease (dropUser), not by the database itself.