/ /

AWS IAM Authentication Mechanism

Important

The MONGODB-AWS authentication mechanism is available only in MongoDB version 4.4 and later.

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 connect to a MongoDB instance with MONGODB-AWS authentication enabled, specify the MONGODB-AWS authentication mechanism.

The driver checks for your credentials in the following sources in the order listed:

Connection string.
Custom credential provider. To learn more, see Specify a Custom AWS Credential Provider.
Environment variables.
Web identity token file.
AWS ECS endpoint specified in the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable.
AWS EC2 endpoint. To learn more, see IAM Roles for Tasks in the AWS documentation.

Important

The driver obtains the credentials only from the first source in which they are found. For example, if you specify your AWS credentials in the connection string, the driver ignores any credentials that you specify in environment variables.

Tip

The following examples set the appropriate credentials by using the SetAuth() method. You can also specify these credentials by using the ApplyURI() method. If you use the ApplyURI() method you must URL encode the username and password to ensure they are correctly parsed.

To connect to your MongoDB instance using your AWS IAM credentials, perform the following steps:

Assign the AuthMechanism option the value MONGODB-AWS
Assign the Username option the value of your accessKeyID
Assign the Password option the value of your secretAccessKey

var accessKeyID, secretAccessKey string
awsCredential := options.Credential{
	AuthMechanism: "MONGODB-AWS",
	AuthSource:    "<authenticationDb>",
	Username:      "<accessKeyID>",
	Password:      "<secretAccessKey>",
}
awsIAMClient, err := mongo.Connect(options.Client().SetAuth(awsCredential))
if err != nil {
	panic(err)
}
_ = awsIAMClient

If you must specify an AWS session token, use the temporary credentials returned from an assume role request.

To use temporary credentials, assign the value of your sessionToken to the AuthMechanismProperties option:

var accessKeyID, secretAccessKey, sessionToken string
assumeRoleCredential := options.Credential{
	AuthMechanism: "MONGODB-AWS",
	AuthSource:    "<authenticationDb>",
	Username:      "<accessKeyID>",
	Password:      "<secretAccessKey>",
	AuthMechanismProperties: map[string]string{
		"AWS_SESSION_TOKEN": "<sessionToken>",
	},
}
assumeRoleClient, err := mongo.Connect(options.Client().SetAuth(assumeRoleCredential))

To authenticate to your MongoDB instance using AWS credentials stored in environment variables, use a shell to set the variables as follows:

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

Note

If you don't require an AWS session token for the role you're authenticating with, omit the line containing AWS_SESSION_TOKEN.

After you've set the preceding environment variables, specify the MONGODB-AWS authentication mechanism as shown in the following example:

envVariablesCredential := options.Credential{
	AuthMechanism: "MONGODB-AWS",
}
envVariablesClient, err := mongo.Connect(options.Client().SetAuth(envVariablesCredential))
if err != nil {
	panic(err)
}
_ = envVariablesClient

You can use the OpenID Connect (OIDC) token obtained from a web identity provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or other services. To use an OIDC token, create or locate the file that contains your token. Then, set the following environment variables:

AWS_WEB_IDENTITY_TOKEN_FILE: Set to the absolute path of the file that contains your OIDC token.
AWS_ROLE_ARN: Set to the IAM role used to connect to your cluster. For example: arn:aws:iam::111122223333:role/my-role.

The following shell command sets these environment variables:

export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file that contains OIDC token>
export AWS_ROLE_ARN=<IAM role name>

After you set the preceding environment variables, specify the MONGODB-AWS authentication mechanism as shown in the following example:

envVariablesCredential := options.Credential{
	AuthMechanism: "MONGODB-AWS",
}
envVariablesClient, err := mongo.Connect(options.Client().SetAuth(envVariablesCredential))
if err != nil {
	panic(err)
}
_ = envVariablesClient

Specify a Custom AWS Credential Provider

You can supply your own AWS credential provider to the driver, which enables you to use the full credential chain of the AWS SDK for Go v2. If you authenticate by using an AWS mechanism that the driver's built-in credential chain doesn't support, such as Amazon EKS Pod Identity, use this method.

Prerequisites

Before you begin, ensure that you have the following:

Go 1.26 or later
Go driver v2.9 or later

Note

Experimental Feature

The ext/awsauth module is pre-release. Its API is unstable and might change in backward-incompatible ways.

To supply a credential provider from the AWS SDK, install the ext/awsauth module and the AWS SDK for Go v2:

go get go.mongodb.org/mongo-driver/ext/awsauth github.com/aws/aws-sdk-go-v2/config

The following example passes a provider chain from the AWS SDK to the AWS authentication mechanism:

awsConfig, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
	panic(err)
}
awsSdkCredential := options.Credential{
	AuthMechanism:          "MONGODB-AWS",
	AWSCredentialsProvider: awsauth.NewCredentialsProvider(awsConfig.Credentials),
}
awsSdkClient, err := mongo.Connect(options.Client().SetAuth(awsSdkCredential))
if err != nil {
	panic(err)
}
_ = awsSdkClient

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