Docs Menu

Authentication Mechanisms

On this page

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

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.

If you want to establish a connection to your MongoDB cluster without an authentication mechanism, see our Connection Guide.

The Go driver supports the following authentication mechanisms:

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() function of the ClientOptions type.

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

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.

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

For more information on the challenge-response (CR) and salted challenge-response authentication mechanisms (SCRAM) that MongoDB supports, see the SCRAM section of the server manual.

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

Important

The MONGODB-AWS authentication mechanism is only available 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 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))

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)
Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.