Use an AWS IAM User or Role ARN to authenticate a database user. 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.
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_IDAWS_SECRET_ACCESS_KEYAWS_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 gets the credentials from Instance Metadata Service V2 at the following URL:
http://169.254.169.254/latest/meta-data/iam/security-credentials/
To learn more, 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 Add 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
authSourcequery parameter is$external, URL-encoded as%24external.The
authMechanismquery parameter isMONGODB-AWS.Example
mongosh "mongodb+srv://<atlas-host-name>/test?authSource=%24external&authMechanism=MONGODB-AWS" --username <access-key-id> --password <secret-key>