Authentication Mechanisms

Example Conventions

Each authentication mechanism contains the following placeholders:

• username - Your MongoDB username

• password - Your MongoDB 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: "<username>",
   Password: "<password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
   SetAuth(credential)
client, err := mongo.Connect(context.TODO(), 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 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: "<username>",
   Password: "<password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
   SetAuth(credential)
client, err := mongo.Connect(context.TODO(), clientOpts)

SCRAM-SHA-1

SCRAM-SHA-1 is a salted challenge-response mechanism (SCRAM) that uses your username and password, encrypted with 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: "<username>",
   Password: "<password>",
}
clientOpts := options.Client().ApplyURI("mongodb://<hostname>:<port>").
   SetAuth(credential)
client, err := mongo.Connect(context.TODO(), 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 specify the MONGODB-AWS authentication mechanism, perform the following:

• 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(
   context.TODO(),
   options.Client().SetAuth(awsCredential))
if err != nil {
   panic(err)
}
_ = awsIAMClient

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

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

var 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(context.TODO(),
   options.Client().SetAuth(assumeRoleCredential))

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)