AWS Identity and Access Management

On this page

Overview

Code Placeholders
Using AWS IAM Authentication in Your Application
Specify AWS IAM Credentials Manually
Retrieve AWS IAM Credentials Automatically
Web Identity Provider
Shared AWS Credentials File
Environment Variables
ECS Container Credentials
EC2 Container Credentials
API Documentation

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.

Code Placeholders

The code examples on this page use the following placeholders:

<hostname>: The network address of your MongoDB Atlas deployment
<awsKeyId>: Your AWS access key ID
<awsSecretKey>: Your AWS secret access key
<awsSessionToken>: Your AWS session token

To use the code examples on this page, replace these placeholders with your own values.

Using AWS IAM Authentication in Your Application

To use AWS IAM authentication, perform the following steps:

Add the MongoDB.Driver.Authentication.AWS NuGet package to your project. You can add this package by using your IDE or by running the following command in your terminal:
```
dotnet add package MongoDB.Driver.Authentication.AWS
```
Add the following line of code to your application's bootstrap code to register the AWS authentication provider:
```
MongoClientSettings.Extensions.AddAWSAuthentication();
```

After you register the AWS authentication provider, you can either specify your AWS IAM credentials explicitly or instruct the driver to retrieve them automatically from an external source. The following sections describe both of these methods.

Specify AWS IAM Credentials Manually

You can supply your AWS IAM credentials in a MongoClientSettings object either by using a MongoCredential object or as part of the connection string. Select the Connection String or MongoCredential tab to see the corresponding syntax for specifying your credentials:

var connectionString = "mongodb+srv://<awsKeyId>:<awsSecretKey>@<hostname>?" +
   "authSource=$external" +
   "&authMechanism=MONGODB-AWS";
var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString);
var client = new MongoClient(mongoClientSettings);

If you're using an AWS session token, include the authMechanismProperties parameter in the connection string as shown below:

var connectionString = "mongodb+srv://<awsKeyId>:<awsSecretKey>@<hostname>?" +
   "authSource=$external" +
   "&authMechanism=MONGODB-AWS" +
   "&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>";

var mongoClientSettings = MongoClientSettings
    .FromConnectionString("mongodb+srv://<hostname>");
mongoClientSettings.Credential = new MongoCredential(
    "MONGODB-AWS",
    new MongoExternalIdentity("<awsKeyId>"),
    new PasswordEvidence("<awsSecretKey>"));
var client = new MongoClient(mongoClientSettings);

If you're using an AWS session token, call the WithMechanismProperty() method on your MongoCredential object as shown below:

mongoClientSettings.Credential = new MongoCredential(
   "MONGODB-AWS",
   new MongoExternalIdentity("<awsKeyId>"),
   new PasswordEvidence("<awsSecretKey>"))
   .WithMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>");

Retrieve AWS IAM Credentials Automatically

Instead of specifying your AWS IAM credentials in MongoClientSettings, you can instruct the .NET/C# Driver to use the AWS SDK to automatically retrieve your credentials from an external source.

To instruct the driver to retrieve your credentials, you must first specify MONGODB-AWS as the authentication mechanism and specify that authentication source is external to MongoDB. You can specify the authentication mechanism and source either by using a MongoCredential object or as part of the connection string. Select the Connection String or MongoCredential tab to see the corresponding syntax for specifying the MONGODB-AWS authentication mechanism and external authentication source:

var connectionString = "mongodb+srv://<hostname>?" +
   "authMechanism=MONGODB-AWS" +
   "&authSource=$external";
var mongoClientSettings = MongoClientSettings
   .FromConnectionString(connectionString);
var client = new MongoClient(mongoClientSettings);

var mongoClientSettings = MongoClientSettings
   .FromConnectionString("mongodb+srv://<hostname>");
mongoClientSettings.Credential = new MongoCredential(
   "MONGODB-AWS",
   new MongoExternalAwsIdentity(),
   new ExternalEvidence());
var client = new MongoClient(mongoClientSettings);

After you specify the authentication mechanism and source, you must set your credentials in the location appropriate to the credential type. The .NET/C# Driver checks for credentials in the following locations in the order listed here.

Web Identity Provider

You can use an OpenID Connect (OIDC)-compatible web identity provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or other services. To use a web identity provider, create a file that contains your OIDC token, then set the absolute path to this file in an environment variable by using bash or a similar shell as shown in the following example:

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>

Shared AWS Credentials File

To authenticate by using a profile in a shared AWS credentials file, you can use a text editor, the AWS SDK for .NET, or the AWS CLI to create the appropriate credential file.

Environment Variables

To retrieve credentials directly from environment variables, set the following environment variables by using bash or a similar shell:

export AWS_ACCESS_KEY_ID=<awsKeyId>
export AWS_SECRET_ACCESS_KEY=<awsSecretKey>
export AWS_SESSION_TOKEN=<awsSessionToken>

Note

Omit the line containing AWS_SESSION_TOKEN if you don't need an AWS session token for that role.

ECS Container Credentials

To authenticate by using ECS container credentials, set the URI of your ECS endpoint in an environment variable by using bash or a similar shell. Select the Full ECS URI or Relative ECS URI tab to see the syntax for specifying the corresponding environment variable:

export AWS_CONTAINER_CREDENTIALS_FULL_URI=<full ECS endpoint>

export AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=<relative ECS endpoint>

EC2 Container Credentials

To authenticate by using EC2 container credentials, make sure none of the preceding environment variables are set. The driver obtains the credentials from the default IPv4 EC2 instance metadata endpoint.

API Documentation

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

Back

X.509

OIDC