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:
db_username
- Your MongoDB database usernamedb_password
- Your MongoDB database 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: "<db_username>", Password: "<db_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 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(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: "<db_username>", Password: "<db_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.
Tip
The following examples set the appropriate credentials by using the SetAuth()
method. You can also specify these credentials by using the ApplyURI()
method. If you use the ApplyURI()
method you must URL encode the username
and password to ensure they are correctly parsed.
To connect to your MongoDB instance using your AWS IAM credentials, perform the following steps:
Assign the
AuthMechanism
option the valueMONGODB-AWS
Assign the
Username
option the value of youraccessKeyID
Assign the
Password
option the value of yoursecretAccessKey
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 must specify an AWS session token, use the temporary credentials returned from an assume role request.
To use temporary credentials, assign the value of your sessionToken
to
the AuthMechanismProperties
option:
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(context.TODO(), options.Client().SetAuth(assumeRoleCredential))
To authenticate to your MongoDB instance using AWS credentials stored in environment variables, use a shell to set the variables as follows:
export AWS_ACCESS_KEY_ID=<awsKeyId> export AWS_SECRET_ACCESS_KEY=<awsSecretKey> export AWS_SESSION_TOKEN=<awsSessionToken>
Note
If you don't require an AWS session token for the role you're
authenticating with, omit the line containing AWS_SESSION_TOKEN
.
After you've set the preceding environment variables, specify the MONGODB-AWS
authentication mechanism as shown in the following example:
envVariablesCredential := options.Credential{ AuthMechanism: "MONGODB-AWS", } envVariablesClient, err := mongo.Connect( context.TODO(), options.Client().SetAuth(envVariablesCredential)) if err != nil { panic(err) } _ = envVariablesClient
You can use the OpenID Connect (OIDC) token obtained from a web identity provider to authenticate to Amazon Elastic Kubernetes Service (EKS) or other services. To use an OIDC token, create a file that contains your token, then set the absolute path to this file in an environment variable by using a shell as shown in the following example:
export AWS_WEB_IDENTITY_TOKEN_FILE=<absolute path to file containing your OIDC token>
After you've set the preceding environment variable, specify the MONGODB-AWS
authentication mechanism as shown in the following example:
envVariablesCredential := options.Credential{ AuthMechanism: "MONGODB-AWS", } envVariablesClient, err := mongo.Connect( context.TODO(), 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 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)