AWS IAM Authentication Mechanism

Overview

The MONGODB-AWS authentication mechanism uses Amazon Web Services Identity and Access Management (AWS IAM) credentials to authenticate a user to MongoDB. You can use this mechanism only when authenticating to MongoDB Atlas.

Tip

Configure Atlas for AWS IAM Authentication

To learn more about configuring MongoDB Atlas for AWS IAM authentication, see Set Up Authentication with AWS IAM in the Atlas documentation.

Specify MONGODB-AWS Authentication

To use the MONGODB-AWS authentication mechanism, specify 'MONGODB-AWS' as the value of the authMechanism connection option.

Note

The MongoDB PHP Library uses libmongoc's implementation of the MONGODB-AWS authentication mechanism. To learn more about using this authentication mechanism with libmongoc, see Authentication via AWS IAM in the C driver documentation.

When you use the MONGODB-AWS mechanism, the driver tries to retrieve AWS credentials from the following sources, in the order listed:

Options passed to the MongoDB\Client either as part of the connection URI or an options parameter
Environment variables
AWS EKS AssumeRoleWithWebIdentity request
ECS container metadata
EC2 instance metadata

The following sections describe how to retrieve credentials from these sources and use them to authenticate your PHP application.

MongoDB\Client Credentials

First, the driver checks whether you passed AWS credentials to the MongoDB\Client constructor, either as as part of the connection URI or the $uriOptions array parameter. To pass your credentials to MongoDB\Client, set the following connection options:

username: The AWS IAM access key ID to authenticate. Percent-encode this value before including it in a connection URI.
password: The AWS IAM secret access key. Percent-encode this value before including it in a connection URI.
authMechanism: Set to 'MONGODB-AWS'.

You can set these options in two ways: by passing an options array to the MongoDB\Client constructor or through parameters in your connection URI. Select the MongoDB\Client or Connection URI tab to see the corresponding code:

$uriOptions = [
    'username' => '<AWS IAM access key ID>',
    'password' => '<AWS IAM secret access key>',
    'authMechanism' => 'MONGODB-AWS',
];
$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    $uriOptions,
);

$uri = 'mongodb://<AWS IAM access key ID>:<AWS IAM secret access key>@<hostname>:<port>/?authMechanism=MONGODB-AWS';
$client = new MongoDB\Client($uri);

Environment Variables

If you don't provide a username and password when you construct your MongoDB\Client object, the driver tries to retrieve AWS credentials from the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

To use these environment variables to authenticate your application, first set them to the AWS IAM values needed for authentication. You can run the export command in your shell or add the variables to a .env file, as shown in the following code example:

export AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
export AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
export AWS_SESSION_TOKEN=<AWS session token>

AWS_ACCESS_KEY_ID=<AWS IAM access key ID>
AWS_SECRET_ACCESS_KEY=<AWS IAM secret access key>
AWS_SESSION_TOKEN=<AWS session token>

Important

Don't percent-encode the values in these environment variables.

After you set these environment variables, set the authMechanism connection option to 'MONGODB-AWS'.

Example

The following example sets the authMechanism connection option. You can set this option in two ways: by passing an options array to the MongoDB\Client constructor or through a parameter in your connection URI.

$client = new MongoDB\Client(
    'mongodb://<hostname>:<port>',
    ['authMechanism' => 'MONGODB-AWS'],
);

$uri = 'mongodb://<hostname>:<port>/?authMechanism=MONGODB-AWS';
$client = new MongoDB\Client($uri);

Tip

AWS Lambda

AWS Lambda runtimes can automatically set these environment variables during initialization. For more information about using environment variables in an AWS Lambda environment, see Using Lambda environment variables in the AWS documentation.

AssumeRoleWithWebIdentity Request

If your application authenticates users for your EKS cluster from an OpenID Connect (OIDC) identity provider, the driver can make an AssumeRoleWithWebIdentity request to exchange the OIDC token for temporary AWS credentials for your application.

To authenticate with temporary AWS IAM credentials returned by an AssumeRoleWithWebIdentity request, ensure that the AWS config file exists in your environment and is configured correctly. To learn how to create and configure an AWS config file, see Configuration in the AWS documentation.

After you configure your environment for an AssumeRoleWithWebIdentity request, set the authMechanism connection option to 'MONGODB-AWS'. To view an example that sets the authMechanism option, see the authMechanism example on this page.

Tip

For more information about using an AssumeRoleWithWebIdentity request to authenticate your application, see the following AWS documentation:

ECS Metadata

If your application runs in an Elastic Container Service (ECS) container, the driver can automatically retrieve temporary AWS credentials from an ECS endpoint. To do so, specify the URI of the ECS endpoint in an environment variable called AWS_CONTAINER_CREDENTIALS_RELATIVE_URI. You can set this variable by running the export shell command or adding it to your .env file, as shown in the following example:

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<URI of the ECS endpoint>

After you set the environment variable, set the authMechanism connection option to 'MONGODB-AWS'. To view an example that sets the authMechanism option, see the authMechanism example on this page.

EC2 Instance Metadata

The driver can automatically retrieve temporary AWS credentials from an Amazon Elastic Cloud Compute (EC2) instance. To use temporary credentials from within an EC2 instance, set the authMechanism connection option to 'MONGODB-AWS'. To view an example that sets the authMechanism option, see the authMechanism example on this page.

Note

The MongoDB PHP Library retrieves credentials from an EC2 instance only if the environment variables described in the Environment Variables section are not set.

Additional Information

To learn more about creating a MongoDB\Client object in the MongoDB PHP Library, see the Create a MongoDB Client guide.

To learn more about connection options, see the Specify Connection Options guide.

Back

X.509

Encryption