---
layout: docs
page_title: MongoDB Atlas- Database - Secrets Engines
description: |-
  MongoDB Atlas is one of the supported plugins for the database secrets engine. This
  plugin generates database credentials dynamically based on configured roles
  for MongoDB Atlas databases.
---

# MongoDB Atlas database secrets engine

MongoDB Atlas is one of the supported plugins for the database secrets engine. This
plugin generates database credentials dynamically based on configured roles for
MongoDB Atlas databases. It cannot support rotating the root user's credentials because
it uses a public and private key pair to authenticate.

See the [database secrets engine](/vault/docs/secrets/databases) docs for
more information about setting up the database secrets engine.

<Note>
  The information below relates to the MongoDB Altas <b>database plugin</b> for the Vault database secrets engine.
  Refer to the <a href="/vault/docs/secrets/mongodbatlas">MongoDB Atlas secrets engine</a> for
  information about using the MongoDB Atlas secrets engine for the Vault.
</Note>

## Capabilities

| Plugin Name                    | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization | Credential Types             |
| ------------------------------ | ------------------------ | ------------- | ------------ | ---------------------- | ---------------------------- |
| `mongodbatlas-database-plugin` | No                       | Yes           | Yes          | Yes (1.8+)             | password, client_certificate |

## Setup

1.  Enable the database secrets engine if it is not already enabled:

    ```shell-session
    $ 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:

    ```shell-session
    $ vault write database/config/my-mongodbatlas-database \
        plugin_name=mongodbatlas-database-plugin \
        allowed_roles="*" \
        public_key="jmskfortvf" \
        private_key="ea6acbc7-8a30-4a3f-812e-6f869c08bcd1" \
        project_id="4f96cad208574fd14aa8dda3a"
    ```

## Usage

After the secrets engine is configured and a user/machine has a Vault token with
the proper permissions, it can generate credentials.

#### Password credentials

1.  Configure a role that maps a name in Vault to a MongoDB Atlas command that executes and
    creates the database user credential:

    ```shell-session
    $ vault write database/roles/my-password-role \
        db_name=my-mongodbatlas-database \
        creation_statements='{"database_name": "admin","roles": [{"databaseName":"admin","roleName":"atlasAdmin"}]}' \
        default_ttl="1h" \
        max_ttl="24h"
    Success! Data written to: database/roles/my-password-role
    ```

1.  Generate a new credential by reading from the `/creds` endpoint with the name
    of the role:

    ```shell-session
    $ vault read database/creds/my-password-role
        Key                Value
        ---                -----
        lease_id           database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
        lease_duration     1h
        lease_renewable    true
        password           FBYwnnh-fwc0quxtKf11
        username           v-my-password-role-DKbQEg6uRn
    ```

    Each invocation of the command generates a new credential.

    MongoDB Atlas database credentials eventually become consistent when the
    [MongoDB Atlas Admin API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/)
    coordinates with hosted clusters in your Atlas project. You cannot use the
    credentials successfully until the consistency process completes.

    If you plan to use MongoDB Atlas credentials in a pipeline, you may need to add
    a time delay or secondary process to account for the time required to establish consistency.

#### Client certificate credentials

1.  Configure a role that maps a name in Vault to a MongoDB Atlas command that executes and
    creates the X509 type database user credential:

    ```shell-session
    $ vault write database/roles/my-dynamic-certificate-role \
      db_name=my-mongodbatlas-database \
      creation_statements='{"database_name": "$external", "x509Type": "CUSTOMER", "roles": [{"databaseName":"<db_name>","roleName":"readWrite"}]}' \
      default_ttl="1h" \
      max_ttl="24h" \
      credential_type="client_certificate" \
      credential_config=ca_cert="$(cat path/to/ca_cert.pem)" \
      credential_config=ca_private_key="$(cat path/to/private_key.pem)" \
      credential_config=key_type="rsa" \
      credential_config=key_bits=2048 \
      credential_config=signature_bits=256 \
      credential_config=common_name_template="{{.DisplayName}}_{{.RoleName}}_{{unix_time}}"
    Success! Data written to: database/roles/my-dynamic-certificate-role
    ```

1.  Generate a new credential by reading from the `/creds` endpoint with the name
of the role:

    ```shell-session
    $ vault read database/creds/my-dynamic-certificate-role
      Key                 Value
      ---                 -----
      request_id          b6556b2d-c379-5a92-465d-6597c506c821
      lease_id            database/creds/my-dynamic-certificate-role/AZ5tao6NjLJctx7fm1bujKEL
      lease_duration      1h
      lease_renewable     true
      client_certificate  -----BEGIN CERTIFICATE-----
                          ...
                          -----END CERTIFICATE-----
      private_key         -----BEGIN PRIVATE KEY-----
                          ...
                          -----END PRIVATE KEY-----
      private_key_type    rsa
      username            CN=token_my-dynamic-certificate-role_1677262121
    ```

## Client certificate authentication

MongoDB Atlas supports [X.509 client certificate based authentication](https://www.mongodb.com/docs/manual/tutorial/configure-x509-client-authentication/)
for enhanced authentication security as an alternative to username and password authentication.
The MongoDB Atlas database plugin can be used to manage client certificate credentials for
MongoDB Atlas users by using `client_certificate` [credential_type](/vault/api-docs/secret/databases#credential_type).

See the [usage](/vault/docs/secrets/databases/mongodbatlas#usage) section for examples using dynamic roles.

## API

The full list of configurable options can be seen in the [MongoDB Atlas Database
Plugin HTTP API](/vault/api-docs/secret/databases/mongodbatlas) page.

For more information on the database secrets engine's HTTP API please see the
[Database Secrets Engine API](/vault/api-docs/secret/databases) page.
