Authentication using IAM identity

Amazon DocumentDB users and applications can use IAM users and roles to authenticate into an Amazon DocumentDB cluster. Amazon DocumentDB IAM authentication is a password-less authentication method in which user passwords are not stored in the Amazon DocumentDB cluster. Also, client applications do not send the password secrets to the Amazon DocumentDB cluster. Instead, client connections are authenticated by AWS STS using temporary security tokens. Non-administrative users and applications can now use the same IAM identity ARN when connecting to different Amazon DocumentDB clusters and other AWS services.

You can also choose to use both password-based and IAM authentication to authenticate users and applications to an Amazon DocumentDB cluster. IAM authentication is available only in Amazon DocumentDB instance-based cluster version 5.0. IAM authentication using IAM identity ARNs is not supported for the Amazon DocumentDB primary user.

Note

The primary user can only be authenticated using existing password-based authentication.

Getting started with authentication using IAM users and roles

Amazon DocumentDB users and roles with IAM identities are created and managed in an $external database.

Creating a user

Connect as the primary user, then create an IAM user and role:

use $external;
db.createUser(
    {
        user: "arn:aws:iam::123456789123:user/iamuser",
            mechanisms: ["MONGODB-AWS"],
            roles: [ { role: "readWrite", db: "readWriteDB" } ]
    }
);

Alternatively, add an Amazon DocumentDB user using an IAM role:

use $external;
db.createUser(
    {
        user: "arn:aws:iam::123456789123:roles/iamrole",
            mechanisms: ["MONGODB-AWS"],
            roles: [ { role: "readWrite", db: "readWriteDB" } ]
    }
);

Modifying a user

Modify an existing IAM user:

use $external;
db.updateUser(
    {
        "arn:aws:iam::123456789123:user/iamuser",
            { roles: [ { role: "read", db: "readDB" } ] }
    }
);

To grant or revoke roles from an user:

use $external;
db.grantRolesToUser("arn:aws:iam::123456789123:user/iamuser", [{db: "admin", role: "readWriteAnyDatabase"}])

use $external;
db.revokeRolesFromUser("arn:aws:iam::123456789123:user/iamuser", [{db: "admin", role: "readWriteAnyDatabase"}])

Dropping a user

To drop an existing IAM user:

use $external
db.dropUser(
    {
        user: "arn:aws:iam::123456789123:user/iamuser"
    }
);

Configure a connection URI to authenticate using AWS IAM

To authenticate using MONGODB-AWS, use authSource as $external and authMechanism as MONGODB-AWS. The username and password fields are replaced by an Access Key and Secret Key for the IAM user respectively. If you are assuming an IAM role, specify the security token for the assumed session. If you are using MongoDB drivers that support the MONGODB-AWS authentication mechanism, the drivers also have the ability to retrieve IAM role credentials from the compute instance (for example, Amazon EC2, Lambda function, and others). The following example uses a mongo shell to authenticate using MONGODB-AWS by passing an Access Key and Secret Key (of an IAM user) manually to demonstrate authentication against Amazon DocumentDB.

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

Configuring AWS compute types to authenticate to Amazon DocumentDB using AWS IAM

Using Amazon EC2

Amazon EC2 uses the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

Using AWS Lambda

AWS Lambda uses the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

For more information about environment variables, see Using Lambda environment variables in the AWS Lambda Developer Guide.

Using Amazon EKS

Amazon Elastic Kubernetes Service (Amazon EKS) uses the following environment variables:

AWS_WEB_IDENTITY_TOKEN_FILE - path of web identity token file
AWS_ROLE_ARN - Name of IAM role to connect with

For more info on Amazon EKS, see What is Amazon EKS in the Amazon EKS User Guide.

Monitoring IAM authentication requests

Using Amazon DocumentDB auditing

Go to the audit log folder in Amazon CloudWatch, and use different search patterns to get the logs for IAM authentication. For example, use { $.param.mechanism = "MONGODB-AWS" } as the search pattern for “Search all log streams”.

For more info on supported events in auditing, see Auditing Amazon DocumentDB Events.

Using Amazon CloudWatch metrics

StsGetCallerIdentityCalls: This metric shows how many GetCallerIdentity calls an Amazon DocumentDB instance is making to the regionalized AWS Security Token Service (AWS STS) endpoint. Please refer to the MONGODB-AWS authentication specification on why database instances need to make STS GetCallerIdentity calls.

Using IAM authentication

When you don’t want to manage the username and password in your own database, you can use IAM authentication. IAM authentication is available only in Amazon DocumentDB instance-based cluster version 5.0.

IAM authentication has a dependency on the STS service. We recommend you evaluate whether you can lower your connection rate when you are using IAM authentication for the connection and getting an STS throttling exception.

For IAM quotas, see IAM and AWS STS quotas.

Supported IAM drivers

Drivers that support Amazon DocumentDB 5.0 and the MONGODB-AWS authentication mechanism should work with the IAM Authentication implementation in Amazon DocumentDB. There is a known limitation with NodeJS drivers which are currently not supported by Amazon DocumentDB for IAM Authentication. NodeJS driver support will be updated once the limitation is resolved.