Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/
Development
/
Authentication
Docs Home
/
Development
/
Authentication
Docs Home
/
Development
/
Authentication

AWS IAM Authentication

Note

The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see Shared Responsibility Model.

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.

To learn how to configure an AWS IAM role for authentication with AWS ECS Fargate, see the Amazon ECS task execution 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

Back

Authentication

Next

LDAP

On this page