192 lines
7.7 KiB
Plaintext
192 lines
7.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: MongoDB Atlas - Secrets Engines
|
|
description: |-
|
|
The MongoDB Atlas Secrets Engine for Vault generates MongoDB Atlas
|
|
Programmatic API Keys dynamically.
|
|
---
|
|
|
|
# MongoDB Atlas Secrets Engine
|
|
|
|
The MongoDB Atlas Secrets Engine generates Programmatic API keys. The created MongoDB Atlas secrets are
|
|
time-based and are automatically revoked when the Vault lease expires, unless renewed.
|
|
|
|
Vault will create a Programmatic API key for each lease that provide appropriate access to the defined MongoDB Atlas
|
|
project or organization with appropriate role(s). The MongoDB Atlas Programmatic API Key Public and
|
|
Private Keys are returned to the caller. To learn more about Programmatic API Keys visit the
|
|
[Programmatic API Keys Doc](https://docs.atlas.mongodb.com/reference/api-docs/apiKeys/).
|
|
|
|
## Setup
|
|
|
|
Most Secrets Engines must be configured in advance before they can perform their functions. These
|
|
steps are usually completed by an operator or configuration management tool.
|
|
|
|
1. Enable the MongoDB Atlas Secrets Engine:
|
|
|
|
```bash
|
|
$ vault secrets enable mongodbatlas
|
|
Success! Enabled the mongodbatlas Secrets Engine at: mongodbatlas/
|
|
```
|
|
|
|
By default, the Secrets Engine will mount at the name of the engine. To
|
|
enable the Secrets Engine at a different path, use the `-path` argument.
|
|
|
|
1. It's necessary to generate and configure a MongoDB Atlas Programmatic API Key for your organization
|
|
or project that has sufficient permissions to allow Vault to create other Programmatic API Keys.
|
|
|
|
In order to grant Vault programmatic access to an organization or project using only the
|
|
[API](https://docs.atlas.mongodb.com/api-docs/) you need to create a MongoDB Atlas Programmatic API
|
|
Key with the appropriate roles if you have not already done so. A Programmatic API Key consists
|
|
of a public and private key, so ensure you have both. Regarding roles, the Organization Owner and
|
|
Project Owner roles should be sufficient for most needs, however be sure to check what each role
|
|
grants in the [MongoDB Atlas Programmatic API Key User Roles documentation](https://docs.atlas.mongodb.com/reference/user-roles/).
|
|
It is recommended to set an IP Network Access list when creating the key.
|
|
|
|
For more detailed instructions on how to create a Programmatic API Key in the Atlas UI, including
|
|
available roles, visit the [Programmatic API Key documentation](https://docs.atlas.mongodb.com/configure-api-access/#programmatic-api-keys).
|
|
|
|
1. Once you have a MongoDB Atlas Programmatic Key pair, as created in the previous step, Vault can now
|
|
be configured to use it with MongoDB Atlas:
|
|
|
|
```bash
|
|
$ vault write mongodbatlas/config \
|
|
public_key=yhltsvan \
|
|
private_key=2c130c23-e6b6-4da8-a93f-a8bf33218830
|
|
```
|
|
|
|
Internally, Vault will connect to MongoDB Atlas using these credentials. As such,
|
|
these credentials must be a superset of any policies which might be granted
|
|
on API Keys.
|
|
|
|
~> **Note:** It is highly recommended to _not_ use your MongoDB Atlas root account credentials.
|
|
Generate a dedicated Programmatic API key with appropriate roles instead.
|
|
|
|
## Programmatic API Keys
|
|
|
|
Programmatic API Key credential types use a Vault role to generate a Programmatic API Key at
|
|
either the MongoDB Atlas Organization or Project level with the designated role(s) for programmatic access.
|
|
|
|
Programmatic API Keys:
|
|
|
|
- Have two parts, a public key and a private key
|
|
- Cannot be used to log into Atlas through the user interface
|
|
- Must be granted appropriate roles to complete required tasks
|
|
- Must belong to one organization, but may be granted access to any number of
|
|
projects in that organization.
|
|
- May have an IP Network Access list configured and some capabilities may require a
|
|
Network Access list to be configured (these are noted in the MongoDB Atlas API
|
|
documentation).
|
|
|
|
Create a Vault role for a MongoDB Atlas Programmatic API Key by mapping appropriate arguments to the
|
|
organization or project designated:
|
|
|
|
- Organization API Key: Set `organization_id` argument with the appropriate
|
|
[Organization Level Roles](https://docs.atlas.mongodb.com/reference/user-roles/#organization-roles).
|
|
- Project API Key: Set `project_id` with the appropriate [Project Level Roles](https://docs.atlas.mongodb.com/reference/user-roles/#project-roles).
|
|
|
|
~> **Note:** Programmatic API keys can belong to only one Organization but can belong to one or more Projects.
|
|
|
|
Examples:
|
|
|
|
```shell-session
|
|
$ vault write mongodbatlas/roles/test \
|
|
organization_id=5b23ff2f96e82130d0aaec13 \
|
|
roles=ORG_MEMBER
|
|
```
|
|
|
|
```shell-session
|
|
$ vault write mongodbatlas/roles/test \
|
|
project_id=5cf5a45a9ccf6400e60981b6 \
|
|
roles=GROUP_DATA_ACCESS_READ_ONLY
|
|
```
|
|
|
|
## Programmatic API Key Network Access list
|
|
|
|
~> **Note:** MongoDB Atlas has deprecated whitelists, and the API will be disabled in June 2021. It is replaced by a
|
|
similar access list API which is live now. If you specify CIDR blocks or IP addresses to allow, you need to run **Vault
|
|
1.6.3 or greater** to avoid interruption. See [MongoDB Atlas documentation](https://docs.atlas.mongodb.com/reference/api-docs/access-lists/)
|
|
for further details.
|
|
|
|
Programmatic API Key access can and should be limited with a IP Network Access list. In the following example both a CIDR
|
|
block and IP address are added to the IP Network Access list for Keys generated with this Vault role:
|
|
|
|
```bash
|
|
$ vault write atlas/roles/test \
|
|
project_id=5cf5a45a9ccf6400e60981b6 \
|
|
roles=GROUP_CLUSTER_MANAGER \
|
|
cidr_blocks=192.168.1.3/32 \
|
|
ip_addresses=192.168.1.3
|
|
```
|
|
|
|
Verify the created Programmatic API Key Vault role has the added CIDR block and IP address by running:
|
|
|
|
```bash
|
|
$ vault read atlas/roles/test
|
|
|
|
Key Value
|
|
--- -----
|
|
cidr_blocks [192.168.1.3/32]
|
|
ip_addresses [192.168.1.3]
|
|
max_ttl 1h
|
|
organization_id n/a
|
|
roles [GROUP_CLUSTER_MANAGER]
|
|
project_id 5cf5a45a9ccf6400e60981b6
|
|
roles n/a
|
|
ttl 30m
|
|
```
|
|
|
|
## TTL and Max TTL
|
|
|
|
Programmatic API Keys Vault have a time-to-live (TTL) and maximum time-to-live (Max TTL).
|
|
When a credential expires it's automatically revoked. You can set the TTL and Max TTL for each role
|
|
or by tuning the secrets engine's configuration.
|
|
|
|
The following creates a Vault role "test" for a Project level Programmatic API key with a 2 hour time-to-live and a
|
|
max time-to-live of 5 hours.
|
|
|
|
```shell-session
|
|
$ vault write mongodbatlas/roles/test \
|
|
project_id=5cf5a45a9ccf6400e60981b6 \
|
|
roles=GROUP_DATA_ACCESS_READ_ONLY \
|
|
ttl=2h \
|
|
max_ttl=5h
|
|
```
|
|
|
|
You can verify the role that you have created with:
|
|
|
|
```shell-session
|
|
$ vault read mongodbatlas/roles/test
|
|
|
|
Key Value
|
|
--- -----
|
|
organization_id 5b71ff2f96e82120d0aaec14
|
|
roles [GROUP_DATA_ACCESS_READ_ONLY]
|
|
project_id 5cf5a45a9ccf6400e60981b6
|
|
roles n/a
|
|
ttl 2h0m0s
|
|
max_ttl 5h0m0s
|
|
```
|
|
|
|
## Generating Credentials
|
|
|
|
After a user has authenticated to Vault has has sufficient permissions, a read request to the
|
|
`creds` endpoint for the role will generate and return new Programmatic API Keys:
|
|
|
|
```shell-session
|
|
$ vault read mongodbatlas/creds/test
|
|
|
|
Key Value
|
|
--- -----
|
|
lease_id mongodbatlas/creds/test/0fLBv1c2YDzPlJB1PwsRRKHR
|
|
lease_duration 2h
|
|
lease_renewable true
|
|
description vault-test-1563980947-1318
|
|
private_key 905ae89e-6ee8-40rd-ab12-613t8e3fe836
|
|
public_key klpruxce
|
|
```
|
|
|
|
## API
|
|
|
|
The MongoDB Atlas secrets engine has a full HTTP API. Please see the
|
|
[MongoDB Atlas secrets engine API docs](/vault/api-docs/secret/mongodbatlas) for more details.
|