AWS Database Blog

Use IAM authentication with Amazon DocumentDB (with MongoDB compatibility)

Amazon DocumentDB (with MongoDB compatibility) is a fully managed native JSON document database that makes it straightforward and cost-effective to operate critical document workloads at virtually any scale without managing infrastructure. You can use the same application code written using the MongoDB API (versions 3.6, 4.0, and 5.0) compatible drivers, and tools to run, manage, and scale workloads on Amazon DocumentDB without worrying about managing the underlying infrastructure. As a document database, Amazon DocumentDB makes it straightforward to store, query, and index JSON data.

AWS Identity and Access Management (IAM) provides fine-grained access control across all of AWS.

Amazon DocumentDB now supports authentication of database users using IAM – users and applications can authenticate to Amazon DocumentDB clusters using IAM users and roles. Amazon DocumentDB IAM authentication is a password-less authentication method; user passwords are not stored in an Amazon DocumentDB cluster and client applications don’t have to configure and maintain the password secrets when connecting to an Amazon DocumentDB cluster. This feature does not incur any additional charge and is available in Amazon DocumentDB instance-based cluster version 5.0.

In this post, we discuss this new feature and provide you resources on how to enable IAM authentication in your Amazon DocumentDB cluster.

You can benefit from this new feature in one or more of the following use cases:

  • Have a consistent authentication mechanism for other services you might be using in the AWS ecosystem
  • Centralize authentication using IAM and remove your dependency on user name and password pairs
  • Streamline access management for applications and users by reusing existing IAM credentials for authorization
  • Simplify your application development with AWS Lambda and Amazon Elastic Compute Cloud (Amazon EC2) applications by being able to use IAM to authenticate to Amazon DocumentDB instead of user name and password pairs
  • Align with MongoDB authentication mechanisms, providing ease of migration.

Solution overview

In our example use case, an application is running on Amazon Elastic Container Service (Amazon ECS) and needs to store media files on Amazon Simple Storage Service (Amazon S3) and customer data on Amazon DocumentDB. Before the launch of IAM authentication integration for Amazon DocumentDB, the application code would use two separate authentication mechanisms: IAM for Amazon S3 and a user name and password pair managed by AWS Secrets Manager.

The following diagram shows the architecture highlighting the authentication mechanisms prior to the launch of IAM integration for Amazon DocumentDB.

DocumentDB authentication before IAM

With the launch of IAM authentication support for DocumentDB, the application code uses IAM as a unified authentication mechanism for both Amazon S3 and Amazon DocumentDB.

The following diagram shows the architecture highlighting the authentication mechanisms after the launch of IAM integration for Amazon DocumentDB.

DocumentDB authentication after IAM

This solution offers the following features:

  • You can still use the user name and password authentication. The admin user that needs to be created at the time of cluster creation can only be created with the user name and password mechanism.
  • You can also choose to use both password-based and IAM authentication to authenticate users and applications to an Amazon DocumentDB cluster.
  • Authorization is still managed at the database level.

Enable IAM authentication in your cluster

For instructions to enable IAM authentication, refer to Authentication using IAM identity.

For samples, refer to the following GitHub repositories:

After you create the user and associate it with Amazon DocumentDB, you can assign roles and enforce least privilege with role-based access control.

Application changes required

Drivers that support the Amazon DocumentDB 5.0 and MONGODB-AWS authentication mechanism should work with the IAM authentication implementation in Amazon DocumentDB—except for NodeJS driver. For more details, refer to Supported IAM drivers.

The only changes required are in the Amazon DocumentDB connection URL. The two important parameters to add are the following:

  • authSource=$external
  • authMechanism=MONGODB-AWS.

Conclusion

The new IAM authentication feature enables you to manage Amazon DocumentDB user authentication using a consistent mechanism just like you would with other AWS services, thereby simplifying AWS user management and aligning to your organization policies for security.

Try the new feature out, and let us know your feedback and questions in the comments section.

About the Authors

Sourav Biswas is a Senior Amazon DocumentDB Specialist Solutions Architect at AWS. He has been helping Amazon DocumentDB customers successfully adopt the service and implement best practices around it. Before joining AWS, he worked extensively as an application developer and solutions architect for various NoSQL vendors.

Vin Yu is a Principal Product Manager on the Amazon DocumentDB team at AWS. He is passionate about building products and working with developers to solve complex problems.