How do I handle IAM based authentication issues with Amazon DocumentDB?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

If you use AWS Identity and Access Management (IAM) to authenticate to Amazon DocumentDB, then you might receive the "MongoServerError: Authentication failed" error. If you misconfigured the permissions for your IAM entity, then you might also receive an authentication error when you use IAM roles.

Note: Amazon DocumentDB supports IAM based authentication only on cluster version 5.0 and later, with instance-based clusters. The Amazon DocumentDB primary user doesn't support IAM based authentication.

Review the database user and role configuration

Complete the following steps:

1. Use the MongoDB shell to log in to your Amazon DocumentDB cluster as a root user.

2. To check whether your IAM entity (IAM user or IAM role ARN) is correctly set up in the $external database, run the following commands in the MongoDB shell:

   use $external;
   show users;

3. Make sure that you registered the IAM ARN for IAM user and IAM role in the $external database. Also confirm that you assigned the required roles and permissions for the target database.

Validate the connection string

When you connect to the Amazon DocumentDB cluster, make sure that your client specifies both AuthSource and AuthMechanism correctly in the connection string. IAM authentication requires you to use MONGODB-AWS mechanism with AuthSource=$external.

Use IAM authentication to connect to the MongoDB cluster

Confirm that your IAM user or IAM role has the appropriate permissions to access the MongoDB cluster:

mongo "mongodb://<access_key>:<secret_key>@<cluster_endpoint>:<db_port>/test?authSource=%24external&authMechanism=MONGODB-AWS"

Note: Replace access_key with your AWS access key ID. Replace secret_key with your AWS secret key. Replace cluster_endpoint with your Amazon DocumentDB cluster endpoint. Replace db_port with your database port number. The default database port number is 27017.

Use AWS environment credentials to connect to the MongoDB cluster

Confirm that you can connect to the MongoDB cluster with your AWS environment credentials:

mongo "mongodb://<cluster_endpoint>:<db_port>/test?authSource=%24external&authMechanism=MONGODB-AWS"

Note: Replace cluster_endpoint with your Amazon DocumentDB cluster endpoint. Replace db_port with your database port number. The default database port number is 27017.

The client automatically retrieves temporary credentials from the environment. This includes credentials from the following AWS service roles:

• Amazon Elastic Cloud Compute (Amazon EC2) instance profile
• Amazon Elastic Container Service (Amazon ECS) task role
• AWS Lambda execution role
• Amazon Elastic Kubernetes Service (Amazon EKS) service account role.

Validate the IAM role or IAM user is active on the client

If you don't explicitly pass AWS credentials for Amazon EC2 or AWS Lambda, then make sure that you attached an IAM role to the compute resource.

If you don't explicitly pass AWS credentials for Amazon EKS, then verify that the pod or service account has proper IAM role annotation and mapping. Also, make sure that the you attached an IAM role to the compute resource.

To check the effective IAM identity, run the following get-caller-identity command:

aws sts get-caller-identity

Example output:

{
    "UserId": "AIDATOCZW5HO####T22",
    "Account": "236411349###",
    "Arn": "arn:aws:iam::`444455556666`:user/DocDBRole"
}

If the output matches the IAM user or IAM role, then the $external database has your ARN configured correctly.

Note: Amazon DocumentDB doesn't support Node.js drivers versions 6.13.1 and earlier. To use Node.js drivers with IAM for Amazon DocumentDB, you must upgrade Node.js drivers and tools to versions later than 6.13.1.

Related information

Authentication using IAM identity