/ /

Advanced Security Options

Docs Home

Development

Data Federation

Advanced Security Options

Docs Home

Development

Data Federation

Advanced Security Options

Atlas Data Federation Authentication Methods

Atlas Data Federation supports many authentication methods so that you can connect to your federated database instances. You can authenticate using AWS IAM credentials for passwordless access from AWS environments, or using X.509 certificates for mutual TLS authentication. Select your authentication method to view the configuration steps.

AWS IAM Authentication (Federated Database Instance)

Overview

You can use AWS IAM Users or Roles to authenticate database users to your Atlas clusters without managing passwords. Using AWS IAM reduces the number of authentication mechanisms and number of secrets to manage. Atlas does not receive your authentication secret key over the wire and the driver does not persist it.

Choose the appropriate authentication method for your use case:

IAM Roles: Roles that AWS services (EC2, Lambda, ECS) or federated users assume. We recommend that you use IAM Roles for application and workload access for workloads running on AWS compute resources.
IAM Users: Individual AWS users that need direct database access. This option might suit applications running with specific user credentials. For human users such as developers and administrators, we recommend that you use Workforce Identity Federation with OIDC for a direct SSO experience with your identity provider.

Important

Before clients can connect using AWS IAM database authentication, you must create database users that are configured for IAM authentication. To learn how to create database users that use IAM Users or IAM Roles for authentication, see Manage Database Users.

Note

Atlas uses AWS STS to verify the identity of IAM users and roles. AWS enforces a default request quota of 600 requests per second, per account, per region. This quota is applied against the AWS account of the IAM user or role.

Set Up Authentication with AWS IAM Roles

You can set up AWS IAM Roles to authenticate AWS compute types to your Atlas clusters.

Note

You can't set up authentication for AWS IAM principals when LDAP authorization is enabled.

If you require authentication for an AWS IAM principal, consider moving the clusters that you want to access with AWS IAM authentication into another project where LDAP authorization is disabled.

For AWS Lambda and HTTP (ECS and EC2), drivers automatically read from the environment variables. For AWS EKS, you must manually assign the IAM role.

This page describes how AWS Lambda, AWS ECS, and AWS EKS can connect using an AWS IAM role.

Note

You must assign an IAM role to Lambda, EC2, ECS, or EKS in the AWS console.

AWS Lambda passes information to functions through the following environment variables if you assign an execution role to the lambda function.

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

Note

You don't need to manually create these environment variables when you use an execution role in your function.

To learn more about these environment variables, see Using AWS Lambda environment variables.

AWS ECS gets the credentials from the following URI:

http://169.254.170.2${AWS_CONTAINER_CREDENTIALS_RELATIVE_URI}

AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is an environment variable. To learn more, see IAM Roles for Tasks in the AWS documentation.

AWS EC2 instances get credentials automatically from the Instance Metadata Service V2 when an IAM role is attached. The credentials are retrieved from the following URL:

http://169.254.169.254/latest/meta-data/iam/security-credentials/

Important

You must attach an IAM role to your EC2 instance for authentication to work. The IAM role must have the necessary permissions to access your Atlas clusters.

To learn how to attach an IAM role to your EC2 instance, see Launch an instance with an IAM role in the AWS documentation.

For AWS EKS, you must first assign the IAM role to your pod to set up the following environment variables in that pod:

AWS_WEB_IDENTITY_TOKEN_FILE - contains the path to the web identity token file.
AWS_ROLE_ARN - contains the IAM role used to connect to your cluster.

To learn more about AWS EKS, see What is Amazon EKS? in the AWS documentation.

Grant Database Access to AWS IAM Roles

To grant database access to the AWS IAM role, complete the steps described in the Configure Database Users section for AWS IAM. For more information on granting database access using Atlas CLI, Atlas Administration API, or Atlas UI, see Configure Database Users.

Connect to Atlas Cluster Using AWS IAM

To connect to Atlas with your AWS IAM credentials using mongosh, provide a connection string that specifies the MONGODB-AWS authentication mechanism. This connection string format applies to all AWS IAM authentication mechanisms.

Important

You must configure authentication using one of the methods described in Set Up Authentication with AWS IAM Roles before you can use this connection string format.

Connecting to Atlas using AWS IAM authentication with the mongosh requires shell version v0.9.0 or higher.

Consider the following:

Use your AWS IAM credentials, using your access key ID as your username and your secret key as your password.
The authSource query parameter is $external, URL-encoded as %24external.
The authMechanism query parameter is MONGODB-AWS.
Example
mongosh "mongodb+srv://<atlas-host-name>/test?authSource=%24external&authMechanism=MONGODB-AWS" --username <access-key-id> --password <secret-key>

Tip

IAM roles for service accounts

X509 Authentication (Federated Database Instance)

X.509 certificates provide database users access to the clusters in their project. Note that Database users are different from Atlas users. Database users have access to MongoDB databases, while Atlas users have access to the Atlas application itself.

X.509 certificates can be of one of the following types:

Self-managed certificates. With self-managed certificates, you must provide a Certificate Authority (CA) and generate your own certificates for your database users. See Configure a Project to use a Public Key Infrastructure for more details on setting up self-managed certificates in your project.
Atlas-managed certificates. With Atlas-managed certificates, Atlas manages your CA as well and generates the certificates for your database users. You do not need to handle any additional CA configuration with Atlas-managed certificates.

Prerequisites

To self-manage your X.509 certificates, you must have a Public Key Infrastructure (PKI) to integrate with Atlas.

Configure a Project to use a Public Key Infrastructure

If you choose to work with self-managed X.509 certificates, you must configure your project to use a PKI you provide.

In Atlas, go to the Advanced page for your project.

If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
If it's not already displayed, select your project from the Projects menu in the navigation bar.
In the sidebar, click Database & Network Access under the Security heading.
In the sidebar, click Advanced.
The Advanced page displays.

Turn on Self-Managed X.509 Authentication.

Toggle Self-Managed X.509 Authentication to ON.

Provide a PEM-encoded Certificate Authority.

To save one customer-managed X.509 configuration for the project you specify using the Atlas CLI, run the following command:

atlas security customerCerts create [options]

To learn more about the command syntax and parameters, see the Atlas CLI documentation for atlas security customerCerts create.

You can provide a Certificate Authority (CA) using the Atlas UI by either:

Clicking Upload and selecting a .pem file from your filesystem and clicking Save.
Copying the contents of a .pem file into the provided text area and clicking Save.

You can concatenate multiple CAs in the same .pem file or in the text area. Users can authenticate with certificates generated by any of the provided CAs.

When you upload a CA, a project-level alert is automatically created to send a notification 30 days before the CA expires, repeating every 24 hours. You can view and edit this alert from Atlas's Alert Settings page. For more information on configuring alerts, see Configure Alert Settings.

Click Save.

To edit your CA once uploaded, click the Self-Managed X.509 Authentication Settings icon.

Add a Database User using Self-Managed X.509 Authentication

In Atlas, go to the Database & Network Access page for your project.

If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.
If it's not already displayed, select your project from the Projects menu in the navigation bar.
In the sidebar, click Database & Network Access under the Security heading.

The Database & Network Access page displays after you complete the preceding steps.

Open the Add New Database User dialog box.

If it isn't already displayed, click the Database Users tab.
Click Add New Database User.

Select CERTIFICATE.

Enter user information.

Field

Description

Common Name

The user's Common Name (CN) protected by the TLS/SSL certificate. For more information, see RFC 2253.

For example, if your common name is "Jane Doe", your organization is "MongoDB", and your country is "US", insert the following into the Common Name field:

CN=Jane Doe,O=MongoDB,C=US

User Privileges

You can assign roles in one of the following ways:

Select Atlas admin, which provides the user with readWriteAnyDatabase as well as a number of administrative privileges.
Select readWriteAnyDatabase, which provides the user with privileges to read and write to any database.
Select readAnyDatabase which provides the user with privileges to read any database.
Select Select Custom Role to select a custom role previously created in Atlas. You can create custom roles for database users in cases where the built-in database user roles cannot describe the desired set of privileges. For more information on custom roles, see Configure Custom Database Roles.
Click Add Default Privileges. When you click this option, you can select individual roles and specify the database on which the roles apply. Optionally, for the read and readWrite roles, you can also specify a collection. If you do not specify a collection for read and readWrite, the role applies to all non-system collections in the database.

For more information on the built-in Atlas privileges, see Built-In Roles.

For more information on authorization, see Role-Based Access Control and Built-in Roles in the MongoDB manual.

Click Add User.

Back

Advanced Security Options

Advanced User Configuration