open-vault/website/source/docs/secrets/mongodb/index.html.md

layout	page_title	sidebar_current	description
docs	MongoDB - Secrets Engines	docs-secrets-mongodb	The mongodb secrets engine for Vault generates database credentials to access MongoDB.

MongoDB Secrets Engine

~> Deprecation Note: This secrets engine is deprecated in favor of the combined databases secrets engine added in v0.7.1. See the documentation for the new implementation of this secrets engine at MongoDB database plugin.

The mongodb secrets engine for Vault generates MongoDB database credentials dynamically based on configured roles. This means that services that need to access a MongoDB database no longer need to hard-code credentials: they can request them from Vault and use Vault's leasing mechanism to more easily roll them.

Additionally, it introduces a new ability: with every service accessing the database with unique credentials, it makes auditing much easier when questionable data access is discovered: you can track it down to the specific instance of a service based on the MongoDB username.

Vault makes use of its own internal revocation system to ensure that users become invalid within a reasonable time of the lease expiring.

This page will show a quick start for this secrets engine. For detailed documentation on every path, use vault path-help after mounting the secrets engine.

Quick Start

The first step to using the mongodb secrets engine is to mount it. Unlike the kv secrets engine, the mongodb secrets engine is not mounted by default.

$ vault secrets enable mongodb
Success! Enabled the mongodb secrets engine at: mongodb/

Next, we must tell Vault how to connect to MongoDB. This is done by providing a standard connection string (URI):

$ vault write mongodb/config/connection uri="mongodb://admin:Password!@mongodb.acme.com:27017/admin?ssl=true"
Key	Value
---	-----

The following warnings were returned from the Vault server:
* Read access to this endpoint should be controlled via ACLs as it will return the connection URI as it is, including passwords, if any.

In this case, we've configured Vault with the username admin and password Password!, connecting to an instance at mongodb.acme.com on port 27017 with TLS. The user must have privileges to manage users and their roles in the databases Vault will manage users in. The built-in role userAdminAnyDatabase is the simplest way to grant the necessary permissions if we want Vault to manage all users in all databases.

Optionally, we can configure the lease settings for the credentials generated by Vault. This is done by writing to the config/lease key:

$ vault write mongodb/config/lease ttl=1h max_ttl=24h
Success! Data written to: mongodb/config/lease

This restricts each user to being valid or leased for 1 hour at a time, with a maximum total use period of 24 hours. This forces an application to renew its credentials at least hourly and to recycle them once per day.

The next step is to configure a role. A role is a logical name that maps to a policy used to generate MongoDB credentials for that role.

Note that MongoDB also uses roles. The roles you define in Vault are distinct from the built-in and user-defined roles in MongoDB. In fact, when defining a Vault role you may specify the MongoDB roles that should be assigned to users created for that Vault role.

For example, let's create a "readonly" role:

$ vault write mongodb/roles/readonly db=foo roles='[ "readWrite", { "role": "read", "db": "bar" } ]'
Success! Data written to: mongodb/roles/readonly

By writing to the roles/readonly path we are defining the readonly role. Each time Vault is asked for credentials for this role, it will create a user in the specified MongoDB database with the MongoDB roles provided. The username and password of each user created will be dynamically generated by Vault. Just like when creating a user directly using db.createUser, the roles JSON array can specify both built-in roles and user-defined roles for both the database the user is created in and for other databases. Please consult the MongoDB documentation for more details on Role-Based Access Control in MongoDB. In this example, Vault will create a user in the foo database with the readWrite built-in role on that database and the read built-in role on the bar database.

To generate a new set of credentials for a given role, we simply read from the credentials path for that role:

$ vault read mongodb/creds/readonly
Key                Value
---                -----
lease_id           mongodb/creds/readonly/91685212-3040-7dde-48b1-df997c5dc8e7
lease_duration     3600
lease_renewable    true
db                 foo
password           c3faa86d-0f93-9649-de91-c431765e62dd
username           vault-token-48729def-b0ca-2b17-d7b9-3ca7cb86f0ae

By reading from the creds/readonly path, Vault has generated a new set of credentials using the readonly role configuration. Here we see the dynamically generated username and password, along with a one hour lease.

Using ACLs, it is possible to restrict using the mongodb secrets engine such that trusted operators can manage the role definitions, and both users and applications are restricted in the credentials they are allowed to read.

API

The MongoDB secrets engine has a full HTTP API. Please see the MongoDB secrets engine API for more details.