New Vault OSS Now Includes Multi-factor Authentication! Learn more
  • Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.10.x (latest)
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • What is Vault?
  • Use Cases
    • CLI Quick Start
    • HCP Quick Start
    • Developer Quick Start

  • Browser Support
  • Installing Vault
    • Overview
    • Architecture
    • High Availability
    • Integrated Storage
    • Security Model
    • Telemetry
    • Token Authentication
    • Key Rotation
    • Replication
    • Limits and Maximums
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
      • Overview
      • Autopilot
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
      • Overview
      • FAQ
    • Transform
    • Mount Migration
    • Overview
      • Overview
      • TCP
    • replication
      • Overview
      • AliCloud KMS
      • AWS KMS
      • Azure Key Vault
      • GCP Cloud KMS
      • OCI KMS
      • HSM PKCS11 ENT
      • Vault Transit
    • sentinel
      • Overview
      • Consul
      • Kubernetes
      • Overview
      • Aerospike
      • Alicloud OSS
      • Azure
      • Cassandra
      • CockroachDB
      • Consul
      • CouchDB
      • DynamoDB
      • Etcd
      • Filesystem
      • FoundationDB
      • Google Cloud Spanner
      • Google Cloud Storage
      • In-Memory
      • Manta
      • MSSQL
      • MySQL
      • OCI Object Storage
      • PostgreSQL
      • Integrated Storage (Raft)
      • S3
      • Swift
      • Zookeeper
    • telemetry
    • ui
    • Log Completed Requests
    • Entropy Augmentation ENT
    • kms_library ENT
    • Overview
    • agent
      • Overview
      • disable
      • enable
      • list
      • Overview
      • disable
      • enable
      • help
      • list
      • move
      • tune
    • debug
    • delete
      • Overview
      • delete
      • destroy
      • enable-versioning
      • get
      • list
      • metadata
      • patch
      • put
      • rollback
      • undelete
      • Overview
      • lookup
      • renew
      • revoke
      • Overview
      • get
      • inspect
    • list
    • login
    • monitor
    • namespace
      • Overview
      • diagnose
      • generate-root
      • init
      • key-status
      • members
      • migrate
      • raft
      • rekey
      • rotate
      • seal
      • step-down
      • unseal
      • usage
    • path-help
      • Overview
      • deregister
      • info
      • list
      • register
      • reload
      • Overview
      • delete
      • fmt
      • list
      • read
      • write
    • read
      • Overview
      • disable
      • enable
      • list
      • move
      • tune
    • server
    • ssh
    • status
      • Overview
      • capabilities
      • create
      • lookup
      • renew
      • revoke
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers
    • Overview
      • Overview
        • Overview
        • AliCloud
        • AppRole
        • AWS
        • Azure
        • Cert
        • CF
        • GCP
        • JWT
        • Kerberos
        • Kubernetes
        • Overview
        • File
      • Overview
        • Overview
        • Kubernetes
    • Templates
    • Windows service

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • HanaDB
      • IBM Db2
      • InfluxDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
      • Custom
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
    • KMIP ENTERPRISE
      • Overview
      • K/V Version 1
      • K/V Version 2
      • Overview
      • Identity Tokens
      • OIDC Identity Provider
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
    • PKI (Certificates)
    • RabbitMQ
      • Overview
      • Signed Certificates
      • SSH OTP
      • Dynamic Key
    • Terraform Cloud
    • TOTP
      • Overview
      • FF3-1 Tweak Usage
      • Tokenization Transform ENTERPRISE
    • Transit
    • Venafi (Certificates)
    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
      • Overview
      • OIDC Providers
    • Kerberos
    • Kubernetes
    • LDAP
      • Overview
      • FAQ
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID DEPRECATED
    • MFA LEGACY / UNSUPPORTED
    • Overview
    • File
    • Syslog
    • Socket
    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Troubleshoot

    • Overview
      • Overview
      • Agent Injector vs. Vault CSI Provider
        • Overview
        • Running Vault
        • Enterprise Licensing
        • Running Vault on OpenShift
        • Configuration
          • Overview
          • Development
          • Standalone with Load Balanced UI
          • Standalone with TLS
          • Standalone with Audit Storage
          • External Vault
          • Using Kubernetes Auth Method
          • HA Cluster with Consul
          • HA Cluster with Raft
          • HA Enterprise Cluster with Raft
          • HA Enterprise DR Clusters with Raft
          • HA Enterprise Performance Clusters with Raft
          • Vault Agent Injector TLS Configuration
          • Vault Agent Injector TLS with Cert-Manager
        • Overview
        • Annotations
        • Installation
        • Examples
        • Overview
        • Installation
        • Configurations
        • Examples
      • Overview
      • Vault Lambda Extension
      • Running Vault
      • Overview
      • Installation
      • Configuration
      • Troubleshooting
      • Overview
      • Installation
      • Troubleshooting

    • Overview
    • Upgrade Plugins
    • Upgrade to 1.10.x
    • Upgrade to 1.9.x
    • Upgrade to 1.8.x
    • Upgrade to 1.7.x
    • Upgrade to 1.6.3
    • Upgrade to 1.6.2
    • Upgrade to 1.6.1
    • Upgrade to 1.6.0
    • Upgrade to 1.5.3
    • Upgrade to 1.5.2
    • Upgrade to 1.5.1
    • Upgrade to 1.5.0
    • Upgrade to 1.4.6
    • Upgrade to 1.4.5
    • Upgrade to 1.4.4
    • Upgrade to 1.4.1
    • Upgrade to 1.4.0
    • Upgrade to 1.3.10
    • Upgrade to 1.3.9
    • Upgrade to 1.3.8
    • Upgrade to 1.3.5
    • Upgrade to 1.3.4
    • Upgrade to 1.3.3
    • Upgrade to 1.3.2
    • Upgrade to 1.3.0
    • Upgrade to 1.2.7
    • Upgrade to 1.2.6
    • Upgrade to 1.2.5
    • Upgrade to 1.2.4
    • Upgrade to 1.2.1
    • Upgrade to 1.2.0
    • Upgrade to 1.1.2
    • Upgrade to 1.1.1
    • Upgrade to 1.1.0
    • Upgrade to 1.0.0
    • Upgrade to 0.11.6
    • Upgrade to 0.11.2
    • Upgrade to 0.11.0
    • Upgrade to 0.10.4
    • Upgrade to 0.10.2
    • Upgrade to 0.10.0
    • Upgrade to 0.9.6
    • Upgrade to 0.9.3
    • Upgrade to 0.9.2
    • Upgrade to 0.9.1
    • Upgrade to 0.9.0
    • Upgrade to 0.8.0
    • Upgrade to 0.7.0
    • Upgrade to 0.6.4
    • Upgrade to 0.6.3
    • Upgrade to 0.6.2
    • Upgrade to 0.6.1
    • Upgrade to 0.6.0
    • Upgrade to 0.5.1
    • Upgrade to 0.5.0

    • Overview
    • 1.10.0
    • 1.9.0
    • 1.8.0
    • 1.7.0
    • 1.6.0
    • 1.5.0

    • Overview
    • FAQ

    • Overview
    • Feature Deprecation Notice and Plans
    • License
    • Client Count
    • Login MFA
    • Server Side Consistent Token

  • Glossary

    • Overview
      • Overview
      • Autoloading
      • FAQ
    • Replication
      • Overview
      • Behavioral Changes
      • Security
    • Automated Integrated Storage Snapshots
    • Lease Count Quotas
    • Entropy Augmentation
    • Seal Wrap / FIPS 140-2
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
      • Overview
      • Duo MFA
      • Okta MFA
      • PingID MFA
      • TOTP MFA
      • Overview
      • Examples
      • Properties
    • HCP Vault
Type '/' to Search

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

»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:

    $ vault secrets enable mongodbatlas
    Success! Enabled the mongodbatlas Secrets Engine at: mongodbatlas/
    
    $ 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.

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

  3. 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:

    $ vault write mongodbatlas/config \
        public_key=yhltsvan \
        private_key=2c130c23-e6b6-4da8-a93f-a8bf33218830
    
    $ 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.
  • Project API Key: Set project_id with the appropriate Project Level Roles.

Note: Programmatic API keys can belong to only one Organization but can belong to one or more Projects.

Examples:

$ vault write mongodbatlas/roles/test \
    organization_id=5b23ff2f96e82130d0aaec13 \
    roles=ORG_MEMBER
$ vault write mongodbatlas/roles/test \
    organization_id=5b23ff2f96e82130d0aaec13 \
    roles=ORG_MEMBER
$ vault write mongodbatlas/roles/test \
    project_id=5cf5a45a9ccf6400e60981b6 \
    roles=GROUP_DATA_ACCESS_READ_ONLY
$ 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 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:

  $ 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
  $ 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:

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

$ vault write mongodbatlas/roles/test \
    project_id=5cf5a45a9ccf6400e60981b6 \
    roles=GROUP_DATA_ACCESS_READ_ONLY \
    ttl=2h \
    max_ttl=5h
$ 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:

$ 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
$ 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:

$ 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
$ 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 for more details.

github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager