Docs Menu
Docs Home
/
Languages
/
Ruby
/
Ruby MongoDB Driver
/
Security
/
Authentication

AWS Identity and Access Management

On this page

  • Overview
  • Code Placeholders
  • Using AWS IAM Authentication in Your Application
  • Providing Credentials Explicitly
  • Providing Temporary Credentials
  • Automatically Retrieving Credentials
  • API Documentation

Overview

Note

AWS authentication is available only in the MongoDB Enterprise Edition for MongoDB 4.4 and later.

The AWS authentication mechanism uses AWS Identity and Access Management (IAM) and AWS Security Token Service (STS) to prove the client's identity to a MongoDB deployment. The following steps describe the AWS authentication process:

  1. The client uses AWS IAM credentials to create a signature that is sent to the MongoDB deployment.

  2. The deployment uses the client's signature to send a request to AWS STS.

  3. If the request succeeds, STS returns the Amazon Resource Name (ARN) of the IAM user or role that corresponds to the client's credentials.

  4. The deployment uses the returned ARN to look up the user. The client is authenticated as this user.

Note

The client and server use different usernames. The client uses the AWS access key ID, but the server uses the ARN of the IAM user or role corresponding to the access key ID.

AWS credentials include the following components:

  • Access key ID

  • Secret access key

  • Optional session token

Authentication with AWS IAM credentials uses the access key ID and the secret access key. Authentication with temporary AWS IAM credentials uses all three components.

Note

The driver never sends the secret access key or the session token over the network.

Temporary credentials are used with:

Code Placeholders

The code examples on this page use the following placeholders:

  • <hostname>: The network address of your MongoDB deployment

  • <aws-access-key-id>: The AWS access key ID

  • <aws_secret_access_key>: The AWS secret access key

  • <aws_session_token>: The AWS session token

Using AWS IAM Authentication in Your Application

The following sections describe how to use the AWS IAM authentication mechanism in your application.

Providing Credentials Explicitly

You can provide regular (non-temporary) IAM credentials as client options or by using a URI. Select the Connection String or Client Options tab to see the corresponding syntax:

client = Mongo::Client.new(
  'mongodb://<aws_access_key_id>:<aws_secret_access_key>@host/?authMechanism=MONGODB-AWS')
client = Mongo::Client.new(['<host>'],
                           auth_mech: :aws,
                           user: '<aws_access_key_id>',
                           password: '<aws_secret_access_key>')

Note

If you provide credentials in a URI, you must percent-encode them.

Providing Temporary Credentials

To provide temporary credentials, specify the session token in the client options or by using a URI. Select the Connection String or Client Options tab to see the corresponding syntax:

client = Mongo::Client.new(
  'mongodb://<aws_access_key_id>:<aws_secret_access_key>@host/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<<aws_session_token>>')
client = Mongo::Client.new(['<host>'],
                           auth_mech: :aws,
                           user: '<aws_access_key_id>',
                           password: '<aws_secret_access_key>',
                           auth_mech_properties: {
                             aws_session_token: '<<aws_session_token>>',
                           })

Automatically Retrieving Credentials

The client can retrieve credentials from the environment or from EC2 or ECS metadata endpoints. To retrieve credentials automatically, specify the AWS authentication mechanism but do not specify a username or a password. Select the Connection String or Client Options tab to see the corresponding syntax:

client = Mongo::Client.new(
  'mongodb://host/?authMechanism=MONGODB-AWS')
client = Mongo::Client.new(['<hostname>'],
                           auth_mech: :aws)
)

The driver tries to obtain credentials from the following sources, in the specified order:

  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN environment variables. These environment variables are recognized by a variety of AWS-related libraries and tools, such as the official AWS Ruby SDK and the AWS CLI. They are also defined when running in an AWS Lambda environment.

  • AWS STS AssumeRoleWithWebIdentity action. This mechanism returns credentials associated with the service account token, and requires the following environment variables to be set:

    • AWS_WEB_IDENTITY_TOKEN_FILE: Path to a file containing the service account token.

    • AWS_ROLE_ARN: The Amazon Resource Name (ARN) of the role that the caller is assuming.

    • AWS_ROLE_SESSION_NAME (optional): Identifier for the assumed role session. If this variable is empty, the driver generates a random identifier.

  • The AWS ECS task metadata endpoint. This endpoint returns credentials associated with the ECS task role assigned to the container.

  • The AWS EC2 instance metadata endpoint. This endpoint returns credentials associated with the EC2 instance role assigned to the instance.

Important

A credentials source must provide a complete set of credentials. For example, if your application uses the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, the driver raises an error if only one of these variables has a value.

Note

If an application runs in an ECS container on an EC2 instance and the container is allowed access to the instance metadata, the driver attempts to retrieve AWS credentials from the EC2 instance metadata endpoint. If the driver retrieves credentials in this way, your application can authenticate as the IAM role assigned to the EC2 instance.

To learn how to prevent containers from accessing EC2 instance metadata, see the AWS documentation.

API Documentation

To learn more about any of the methods or types discussed on this page, see the following API documentation:

Back

X.509

Next

LDAP (PLAIN)