1--- 2layout: "docs" 3page_title: "MongoDB - Secrets Engines" 4sidebar_title: "MongoDB <sup>DEPRECATED</sup>" 5sidebar_current: "docs-secrets-mongodb" 6description: |- 7 The mongodb secrets engine for Vault generates database credentials to access MongoDB. 8--- 9 10# MongoDB Secrets Engine 11 12~> **Deprecation Note:** This secrets engine is deprecated in favor of the 13combined databases secrets engine added in v0.7.1. See the documentation for 14the new implementation of this secrets engine at 15[MongoDB database plugin](/docs/secrets/databases/mongodb.html). 16 17The `mongodb` secrets engine for Vault generates MongoDB database credentials 18dynamically based on configured roles. This means that services that need 19to access a MongoDB database no longer need to hard-code credentials: they 20can request them from Vault and use Vault's leasing mechanism to more easily 21roll them. 22 23Additionally, it introduces a new ability: with every service accessing 24the database with unique credentials, it makes auditing much easier when 25questionable data access is discovered: you can track it down to the specific 26instance of a service based on the MongoDB username. 27 28Vault makes use of its own internal revocation system to ensure that users 29become invalid within a reasonable time of the lease expiring. 30 31This page will show a quick start for this secrets engine. For detailed documentation 32on every path, use `vault path-help` after mounting the secrets engine. 33 34## Quick Start 35 36The first step to using the mongodb secrets engine is to mount it. Unlike the 37`kv` secrets engine, the `mongodb` secrets engine is not mounted by default. 38 39``` 40$ vault secrets enable mongodb 41Success! Enabled the mongodb secrets engine at: mongodb/ 42``` 43 44Next, we must tell Vault how to connect to MongoDB. This is done by providing 45a standard connection string (URI): 46 47``` 48$ vault write mongodb/config/connection uri="mongodb://admin:Password!@mongodb.acme.com:27017/admin?ssl=true" 49Key Value 50--- ----- 51 52The following warnings were returned from the Vault server: 53* Read access to this endpoint should be controlled via ACLs as it will return the connection URI as it is, including passwords, if any. 54``` 55 56In this case, we've configured Vault with the username `admin` and password 57`Password!`, connecting to an instance at `mongodb.acme.com` on port `27017` 58with TLS. The user must have privileges to manage users and their roles in the 59databases Vault will manage users in. The built-in role `userAdminAnyDatabase` 60is the simplest way to grant the necessary permissions if we want Vault to 61manage all users in all databases. 62 63Optionally, we can configure the lease settings for the credentials generated 64by Vault. This is done by writing to the `config/lease` key: 65 66``` 67$ vault write mongodb/config/lease ttl=1h max_ttl=24h 68Success! Data written to: mongodb/config/lease 69``` 70 71This restricts each user to being valid or leased for 1 hour at a time, with 72a maximum total use period of 24 hours. This forces an application to renew 73its credentials at least hourly and to recycle them once per day. 74 75The next step is to configure a role. A role is a logical name that maps 76to a policy used to generate MongoDB credentials for that role. 77 78Note that MongoDB also uses roles. The roles you define in Vault are distinct 79from the built-in and user-defined roles in MongoDB. In fact, when defining 80a Vault role you may specify the MongoDB roles that should be assigned to 81users created for that Vault role. 82 83For example, let's create a "readonly" role: 84 85``` 86$ vault write mongodb/roles/readonly db=foo roles='[ "readWrite", { "role": "read", "db": "bar" } ]' 87Success! Data written to: mongodb/roles/readonly 88``` 89 90By writing to the `roles/readonly` path we are defining the `readonly` role. 91Each time Vault is asked for credentials for this role, it will create a 92user in the specified MongoDB database with the MongoDB roles provided. The 93username and password of each user created will be dynamically generated by 94Vault. Just like when creating a user directly using `db.createUser`, the 95`roles` JSON array can specify both built-in roles and user-defined roles 96for both the database the user is created in and for other databases. Please 97consult the MongoDB documentation for more details on Role-Based Access 98Control in MongoDB. In this example, Vault will create a user in the `foo` 99database with the `readWrite` built-in role on that database and the `read` 100built-in role on the `bar` database. 101 102To generate a new set of credentials for a given role, we simply read from 103the credentials path for that role: 104 105``` 106$ vault read mongodb/creds/readonly 107Key Value 108--- ----- 109lease_id mongodb/creds/readonly/91685212-3040-7dde-48b1-df997c5dc8e7 110lease_duration 3600 111lease_renewable true 112db foo 113password c3faa86d-0f93-9649-de91-c431765e62dd 114username vault-token-48729def-b0ca-2b17-d7b9-3ca7cb86f0ae 115``` 116 117By reading from the `creds/readonly` path, Vault has generated a new set of 118credentials using the `readonly` role configuration. Here we see the 119dynamically generated username and password, along with a one hour lease. 120 121Using ACLs, it is possible to restrict using the `mongodb` secrets engine such that 122trusted operators can manage the role definitions, and both users and 123applications are restricted in the credentials they are allowed to read. 124 125## API 126 127The MongoDB secrets engine has a full HTTP API. Please see the 128[MongoDB secrets engine API](/api/secret/mongodb/index.html) for more 129details. 130