Authentication Mechanisms

On this page

Overview

Supported Mechanisms
Example Conventions
Default
SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
MONGODB-AWS
X.509

Overview

In this guide, you can learn how to use each authentication mechanism available in the MongoDB Community Edition. MongoDB uses authentication mechanisms to confirm an identity and establish trust to ensure security in the driver and server before connecting.

To authenticate using GSSAPI/Kerberos or LDAP, see the Enterprise Authentication Mechanisms fundamentals page. To learn more about establishing a connection to your MongoDB cluster, see the Connection Guide.

Supported Mechanisms

The Go driver supports the following authentication mechanisms:

SCRAM-SHA-256
SCRAM-SHA-1
MONGODB-CR
MongoDB-AWS
X.509

The Go Driver establishes a connection with an authentication mechanism through a Client type. The Client type specifies the mechanism and credentials to use as connection options in a Credential type . To configure these options, pass a Credential type to the SetAuth() method of the ClientOptions type.

The following sections demonstrate this process by using the five mechanisms the MongoDB Community Edition supports.

Example Conventions

Each authentication mechanism contains the following placeholders:

db_username - Your MongoDB database username
db_password - Your MongoDB database user's password
hostname - Your MongoDB servers network address, accessible by your client
port - Your MongoDB servers port number
authenticationDb - Your MongoDB database that contains the user's authentication data. If you omit this option, the driver uses the default value admin.

Default

The default mechanism uses one of the following authentication mechanisms depending on what MongoDB versions your server supports:

Mechanism	Versions
`SCRAM-SHA-256`	MongoDB 4.0 and later
`SCRAM-SHA-1`	MongoDB 3.0, 3.2, 3.4, and 3.6
`MONGODB-CR`	MongoDB 2.6 and earlier

To specify the default authentication mechanism, omit the AuthMechanism option:

credential := options.Credential{
   AuthSource: "<authenticationDb>",
   Username: "<db_username>",
   Password: "<db_password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
   SetAuth(credential)
client, err := mongo.Connect(clientOpts)

To learn more about the challenge-response (CR) and salted challenge-response authentication mechanisms (SCRAM) that MongoDB supports, see the SCRAM section of the server manual.

`SCRAM-SHA-256`

Important

SCRAM-SHA-256 is the default authentication method for MongoDB starting in MongoDB 4.0.

SCRAM-SHA-256 is a salted challenge-response authentication mechanism (SCRAM) that uses your database username and password, encrypted with the SHA-256 algorithm, to authenticate your user.

To specify the SCRAM-SHA-256 authentication mechanism, assign the AuthMechanism option the value "SCRAM-SHA-256":

credential := options.Credential{
   AuthMechanism: "SCRAM-SHA-256",
   AuthSource: "<authenticationDb>",
   Username: "<db_username>",
   Password: "<db_password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
   SetAuth(credential)
client, err := mongo.Connect(clientOpts)

`SCRAM-SHA-1`

Important

SCRAM-SHA-1 is the default authentication method for MongoDB versions 3.0, 3.2, 3.4, and 3.6.

SCRAM-SHA-1 is a salted challenge-response mechanism (SCRAM) that uses your username and password, encrypted using the SHA-1 algorithm, to authenticate your user.

To specify the SCRAM-SHA-1 authentication mechanism, assign the AuthMechanism option the value "SCRAM-SHA-1":

credential := options.Credential{
   AuthMechanism: "SCRAM-SHA-1",
   AuthSource: "<authenticationDb>",
   Username: "<db_username>",
   Password: "<db_password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
   SetAuth(credential)
client, err := mongo.Connect(clientOpts)

`MONGODB-CR`

MONGODB-CR is a challenge-response authentication mechanism that uses your username and password to authenticate your user.

Important

This authentication mechanism was deprecated starting in MongoDB 3.6 and is no longer supported as of MongoDB 4.0.

`MONGODB-AWS`

Important

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

The MONGODB-AWS authentication mechanism uses your Amazon Web Services Identity and Access Management (AWS IAM) credentials to authenticate your user.

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 they are listed:

Connection string
Environment variables
Web identity token file
AWS ECS endpoint specified in the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable
AWS EC2 endpoint. For more information, see IAM Roles for Tasks.

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 have specified 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 a file that contains your token, then set the absolute path to this file in an environment variable by using a shell as shown in the following example:

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

After you've set the preceding environment variable, 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

`X.509`

The X.509 authentication mechanism uses TLS with X.509 certificates to authenticate your user, identified by the relative distinguished names (RDNs) of your client certificate. When you specify the X.509 authentication mechanism, the server authenticates the connection using the paths of the following files:

tlsCAFile which contains either a single or a bundle of certificate authorities to trust when making a TLS connection
tlsCertificateKeyFile which references the path to the client certificate file or the client private key file

To specify the X.509 authentication mechanism, perform the following:

Assign the tlsCAFile the path to its file in the connection string
Assign the tlsCertificateKeyFile the path to its file in the connection string
Assign the AuthMechanism option the value "MONGODB-X509"

caFilePath := "<cafile_path>"
certificateKeyFilePath := "<client_certificate_path>"
uri := "mongodb://<hostname>:<port>/?tlsCAFile=%s&tlsCertificateKeyFile=%s"
uri = fmt.Sprintf(uri, caFilePath, certificateKeyFilePath)
credential := options.Credential{
   AuthMechanism: "MONGODB-X509",
}
clientOpts := options.Client().ApplyURI(uri).SetAuth(credential)

Back

Context

Enterprise Authentication Mechanisms

Authentication Mechanisms.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-fmznk8{margin-top:-85px;position:absolute;padding-bottom:2px;}

Overview

Supported Mechanisms

Example Conventions

Default

SCRAM-SHA-256

Important

SCRAM-SHA-1

Important

MONGODB-CR

Important

MONGODB-AWS

Important

Important

Tip

Note

X.509

Authentication Mechanisms

`SCRAM-SHA-256`

`SCRAM-SHA-1`

`MONGODB-CR`

`MONGODB-AWS`

`X.509`