Docs Home → Develop Applications → MongoDB Drivers → Go Driver
Authentication Mechanisms
On this page
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:
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:
username
- Your MongoDB usernamepassword
- Your MongoDB user's passwordhostname
- Your MongoDB servers network address, accessible by your clientport
- Your MongoDB servers port numberauthenticationDb
- Your MongoDB database that contains the user's authentication data. If you omit this option, the driver uses the default valueadmin
.
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: "<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
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)
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: "<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.
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 variableAWS 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.
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 connectiontlsCertificateKeyFile
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 stringAssign the
tlsCertificateKeyFile
the path to its file in the connection stringAssign 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)