Skip to content

Setting up AWS IAM authentication

This document provides guidelines how to configure Percona Server for MongoDB to use AWS IAM authentication. The use of this authentication method enables you to natively integrate Percona Server for MongoDB with AWS services, increase security of your infrastructure by setting up password-less authentication and offload your DBAs from managing different sets of secrets. To learn more, see AWS IAM authentication

To configure AWS IAM authentication means to set up your AWS environment and configure Percona Server for MongoDB. The AWS environment setup is out of scope of this document. Consult the AWS documentation to perform the following setup steps:

  1. Configure the AWS resource to work with IAM.

  2. For user authentication:

    For role authentication:

Configure Percona Server for MongoDB

The steps are the following:

  1. Create users in the $external database with the username as the IAM user/role ARN
  2. Enable authentication and specify the authentication mechanism as MONGODB-AWS.

Create users in $external database

During the authentication, Percona Server for MongoDB matches the ARN of the IAM user or role retrieved from AWS STS against the user created in the $external database. Thus, the username for this user must include their ARN and have the following format:

arn:aws:iam::<ARN>:user/<user_name>

arn:aws:iam::<ARN>:role/<role_name>

Create a user and assign the required roles to them. Specify the ARN and names in the following example commands:

> use $external
> db.createUser(
   {
       user: "arn:aws:iam::000000000000:user/myUser",
       roles: [{role: "read", db: "admin"}]
   }
)

> use $external
> db.createUser(
   {
       user: "arn:aws:iam::111111111111:role/myRole",
       roles: [{role: "read", db: "admin"}]
   }
)

Enable authentication

Run the following commands as root or via sudo

  1. Stop the mongod service

    $ sudo systemctl stop mongod

  2. Edit the /etc/mongod.conf configuration file

    security:
  authorization: enabled

setParameter:
  authenticationMechanisms: MONGODB-AWS

  3. Start the mongod service

    $ sudo systemctl start mongod

Configure AWS STS endpoint

By default, all authentication requests are sent to the sts.amazonaws.com endpoint. If this endpoint is unavailable for some reason, you can override it and send AWS STS requests to the endpoints of your choice to ensure successful authentication. You must enable the AWS region to use it.

Edit the /etc/mongod.conf configuration file and specify the AWS endpoint for the awsStsHost parameter.

security:
  authorization: enabled

setParameter:
  authenticationMechanisms: MONGODB-AWS
  awsStsHost: <aws-endpoint>

See the list of AWS endpoints.

Authenticate in Percona Server for MongoDB using AWS IAM

To test the authentication, use either of the following methods:

Replace <aws_access_key_id>, <aws_secret_access_key> and psmdb.example.com with actual values in the following command:

$ mongosh 'mongodb://<aws_access_key_id>:<aws_secret_access_key>:@psmdb.example.com/admin?authSource=$external&authMechanism=MONGODB-AWS'

To pass temporary credentials and AWS token, replace <aws_access_key_id>, <aws_secret_access_key>, <aws_session_token> and psmdb.example.com in the following command:

$ mongosh 'mongodb://<aws_access_key_id>:<aws_secret_access_key>:@psmdb.example.com/admin?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<aws_session_token>'

Set AWS environment variables:

export AWS_ACCESS_KEY_ID='<aws_access_key_id>'
export AWS_SECRET_ACCESS_KEY='<aws_secret_access_key>'
export AWS_SESSION_TOKEN='<aws_session_token>'

Connect to Percona Server for MongoDB:

$ mongosh 'mongodb://psmdb.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS'

If your application is running on the AWS resource, it receives the credentials from the resource metadata. To connect to Percona Server for MongoDB, run the command as follows:

$ mongosh --authenticationMechanism=MONGODB-AWS --authenticationDatabase='$external'

Upon successful authentication, the result should look like the following: 

> db.runCommand( { connectionStatus: 1 })
{
  authInfo: {
    authenticatedUsers: [
      {
        user: 'arn:aws:iam::00000000000:user/myUser',
        db: '$external'
      }
    ],
    authenticatedUserRoles: [ { role: 'read', db: 'admin' } ]
  },
  ok: 1
}

Get expert help

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert