Authentication Mechanisms

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:

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

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

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.

MONGODB-AWS

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:

1. Connection string

2. Environment variables

3. Web identity token file

4. AWS ECS endpoint specified in the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable

5. AWS EC2 endpoint. For more information, see IAM Roles for Tasks.

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

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))

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

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

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

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)