9de0dbaef9
Add note about X.509 SHA-1 deprecation to relevant plugins Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
116 lines
4.3 KiB
Plaintext
116 lines
4.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: MongoDB - Database - Secrets Engines
|
|
description: |-
|
|
MongoDB 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.
|
|
---
|
|
|
|
# MongoDB Database Secrets Engine
|
|
|
|
@include 'x509-sha1-deprecation.mdx'
|
|
|
|
MongoDB 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 and also supports
|
|
[Static Roles](/docs/secrets/databases#static-roles).
|
|
|
|
See the [database secrets engine](/docs/secrets/databases) docs for
|
|
more information about setting up the database secrets engine.
|
|
|
|
## Capabilities
|
|
|
|
| Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization |
|
|
| ------------------------- | ------------------------ | ------------- | ------------ | ---------------------- |
|
|
| `mongodb-database-plugin` | Yes | Yes | Yes | Yes (1.7+) |
|
|
|
|
## Setup
|
|
|
|
1. Enable the database secrets engine if it is not already enabled:
|
|
|
|
```text
|
|
$ vault secrets enable database
|
|
Success! Enabled the database secrets engine at: database/
|
|
```
|
|
|
|
By default, the secrets engine will enable at the name of the engine. To
|
|
enable the secrets engine at a different path, use the `-path` argument.
|
|
|
|
1. Configure Vault with the proper plugin and connection information:
|
|
|
|
```text
|
|
$ vault write database/config/my-mongodb-database \
|
|
plugin_name=mongodb-database-plugin \
|
|
allowed_roles="my-role" \
|
|
connection_url="mongodb://{{username}}:{{password}}@mongodb.acme.com:27017/admin?tls=true" \
|
|
username="vaultuser" \
|
|
password="vaultpass!"
|
|
```
|
|
|
|
1. Configure a role that maps a name in Vault to a MongoDB command that executes and
|
|
creates the database credential:
|
|
|
|
```text
|
|
$ vault write database/roles/my-role \
|
|
db_name=my-mongodb-database \
|
|
creation_statements='{ "db": "admin", "roles": [{ "role": "readWrite" }, {"role": "read", "db": "foo"}] }' \
|
|
default_ttl="1h" \
|
|
max_ttl="24h"
|
|
Success! Data written to: database/roles/my-role
|
|
```
|
|
|
|
## Usage
|
|
|
|
After the secrets engine is configured and a user/machine has a Vault token with
|
|
the proper permission, it can generate credentials.
|
|
|
|
1. Generate a new credential by reading from the `/creds` endpoint with the name
|
|
of the role:
|
|
|
|
```text
|
|
$ vault read database/creds/my-role
|
|
Key Value
|
|
--- -----
|
|
lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
|
|
lease_duration 1h
|
|
lease_renewable true
|
|
password LEm-lcDJ2k0Hi05FvizN
|
|
username v-vaultuser-my-role-ItceCZHlp0YGn90Puy9Z-1602542024
|
|
```
|
|
|
|
## Client x509 Certificate Authentication
|
|
|
|
This plugin supports using MongoDB's [x509 Client-side Certificate Authentication](https://docs.mongodb.com/manual/core/security-x.509/)
|
|
|
|
To use this authentication mechanism, configure the plugin:
|
|
|
|
```shell-session
|
|
$ vault write database/config/my-mongodb-database \
|
|
plugin_name=mongodb-database-plugin \
|
|
allowed_roles="my-role" \
|
|
connection_url="mongodb://@mongodb.acme.com:27017/admin" \
|
|
tls_certificate_key=@/path/to/client.pem \
|
|
tls_ca=@/path/to/client.ca
|
|
```
|
|
|
|
Note: `tls_certificate_key` and `tls_ca` map to [`tlsCertificateKeyFile`](https://docs.mongodb.com/manual/reference/program/mongo/#cmdoption-mongo-tlscertificatekeyfile)
|
|
and [`tlsCAFile`](https://docs.mongodb.com/manual/reference/program/mongo/#cmdoption-mongo-tlscafile) configuration options
|
|
from MongoDB with the exception that the Vault parameters are the contents of those files, not filenames. As such,
|
|
the two options are independent of each other. See the [MongoDB Configuration Options](https://docs.mongodb.com/manual/reference/program/mongo/)
|
|
for more information.
|
|
|
|
## Tutorial
|
|
|
|
Refer to [Database Secrets Engine with
|
|
MongoDB](https://learn.hashicorp.com/tutorials/vault/database-mongodb) for a
|
|
step-by-step tutorial.
|
|
|
|
## API
|
|
|
|
The full list of configurable options can be seen in the [MongoDB database
|
|
plugin API](/api-docs/secret/databases/mongodb) page.
|
|
|
|
For more information on the database secrets engine's HTTP API please see the
|
|
[Database secrets engine API](/api-docs/secret/databases) page.
|