Docs Menu

Docs HomeGo Driver

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.

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.

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.

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

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

  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.

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.

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)
←  ContextEnterprise Authentication Mechanisms →