v1.14.6/website/content/docs/secrets/mongodbatlas.mdx - hashicorp/vault - Git at Google

 ---
 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/).

   <Note>

   The information below relates to the **MongoDB Altas secrets engine**. Refer to the
   [MongoDB Atlas **database** secrets engine](/vault/docs/secrets/databases/mongodbatlas)
   for information about using the MongoDB Atlas database plugin for the Vault
   database secrets engine.

   </Note>

 ## 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.
	---
	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/).

	<Note>

	The information below relates to the MongoDB Altas secrets engine. Refer to the
	[MongoDB Atlas database secrets engine](/vault/docs/secrets/databases/mongodbatlas)
	for information about using the MongoDB Atlas database plugin for the Vault
	database secrets engine.

	</Note>

	## 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.