Authentication
On this page
MongoDB supports a variety of authentication mechanisms.
For more information about configuring your MongoDB server for each of these authentication mechanisms see MongoDB's online documentation.
For more information about users and the Ruby driver's helpers for user management, see the User Management tutorial.
Providing credentials
If authentication is enabled, provide credentials when creating a new client:
client = Mongo::Client.new([ '127.0.0.1:27017' ], user: 'test', password: '123', database: 'mydb' ) # If using a URI: client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb")
Authentication credentials can be changed on a client instance to obtain
a new client using the Client#with method:
authenticated_client = client.with( user: 'another-user', password: '123' )
It is also possible to change the client's database and credentials in one step:
authenticated_music_client = client.with( database: 'music', user:'test', password:'123' )
Auth Source
A user's auth source is the database where that user's authentication credentials are stored.
The user's auth source may be specified whenever the credentials are specified:
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_source: 'admin' ) # If using a URI: client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authSource=admin")
If no auth source is specified, then a default will be assumed by the client. The default auth source depends on the authentication mechanism that is being used to connect.
For the MONGODB-CR, SCRAM-SHA-1, and SCRAM-SHA-256 authentication
mechanisms, the default auth source is the database to which the client is
connecting; if no database is specified, admin database is the default
database and hence the default auth source. For the PLAIN mechanism (LDAP),
the default auth source is the database to which the client is connecting;
if no database is specified, the $external database is used as the
auth source. For the AWS, GSSAPI and MONGODB_X509 mechanisms, the
auth source is always $external.
When a client is constructed using an SRV URI, the driver will look for URI
options in a TXT DNS record that corresponds to the SRV record. Thus, for
example, MongoDB Atlas generally uses the admin database as its auth
source, but this is not specified in SRV URIs because the database is given
as a URI option on the TXT records.
Note that when using SRV URIs, the SRV query and the TXT query are performed separately. On systems where DNS resolution is not 100% reliable, the failure to look up TXT records can cause authentication errors, as the driver may end up using an incorrect auth source. If reliable DNS resolution cannot be guaranteed, the auth source can be specified explicitly in SRV URIs as a URI option:
Mongo::Client.new("mongodb+srv://username:myRealPassword@cluster0.mongodb.net/test?w=majority&authSource=admin")
Note
When changing the database using the with method, the auth source is
determined in the new Client instance using the full set of options
that applies to it. For example, if the original client had an auth source
specified, this auth source would take precedence over the database
given in the with call. If the original client did not have an auth
source specified, the new database would be the new auth source, subject
to the rules of the authentication mechanism used.
Authentication Mechanisms
MongoDB supports several authentication mechanisms, as detailed in this section. Authentication mechanism to use can be explicitly specified when a Client is created; if authentication mechanism is not provided by the application, it is selected as follows:
For MongoDB 4.0 and higher, the client performs SCRAM mechanism negotiation with the server. If the user specified in client configuration permits authentication with SCRAM-SHA-256, then SCRAM-SHA-256 is used for authentication. Otherwise SCRAM-SHA-1 is used.
For MongoDB 3.0 through 3.6, SCRAM-SHA-1 is used.
For MongoDB 2.6, MONGODB-CR is used.
Note that:
X.509, AWS, LDAP and Kerberos authentication mechanisms must always be explicitly requested.
If the MongoDB server that the client is connecting to supports SCRAM, the client will attempt to authenticate using SCRAM if no authentication mechanism is explicitly specified. To authenticate to MongoDB 3.0 and higher servers using MONGODB-CR, the MONGODB-CR mechanism must be explicitly requested.
SCRAM
SCRAM authentication is the default authentication mechanism for MongoDB. There are two SCRAM mechanisms in MongoDB: SCRAM-SHA-1 (available as of MongoDB 3.0) and SCRAM-SHA-256 (available as of MongoDB 4.0). If an authentication mechanism is not specified but user credentials are, the driver will attempt to use SCRAM authentication on server 3.0 or newer and will negotiate the mechanism to use based on the server version and the mechanisms defined for a particular user (it is possible to configure a user in the server to only allow SCRAM-SHA-1 mechanism, only SCRAM-SHA-256 mechanism or both).
To explicitly specify SCRAM-SHA-1 as the authentication mechanism, use the
auth_mech: :scram Ruby client option or the SCRAM-SHA-1 as the value
for the authMechanism URI option, as follows:
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_mech: :scram ) client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authMechanism=SCRAM-SHA-1")
To explicitly specify SCRAM-SHA-256 as the authentication mechanism, use the
auth_mech: :scram256 Ruby client option or the SCRAM-SHA-256 as the
value for the authMechanism URI option, as follows:
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_mech: :scram256 ) client = Mongo::Client.new("mongodb://test:123@127.0.0.1:27017/mydb?authMechanism=SCRAM-SHA-256")
Client Certificate (X.509)
The driver presents an X.509 certificate during TLS negotiation. The MONGODB-X509 authentication mechanism authenticates a username retrieved from the distinguished subject name of this certificate.
Note
Since the username is retrieved from the certificate, a username does not need to be specified. If a username is specified, it will be sent to the server verbatim. If a password is provided, an error will be raised.
This authentication method requires the use of TLS connections with certificate validation.
To authenticate the client, you will need a valid TLS certificate
and private encryption key. These can be stored in separate files,
or together in one file (in the PEM format). Even if the certificate
and private key are stored in the same file, you must specify the path to
that file by passing both the ssl_cert and ssl_key options
to the client.
For more information about configuring X.509 authentication in MongoDB, see the X.509 tutorial in the MongoDB Manual.
client = Mongo::Client.new([ '127.0.0.1:27017' ], auth_mech: :mongodb_x509, ssl: true, ssl_cert: '/path/to/client.pem', ssl_key: '/path/to/client.pem', ssl_ca_cert: '/path/to/ca.pem' )
AWS
Requires MongoDB Enterprise Edition and server version 4.4 or later.
The AWS authentication mechanism uses AWS Identity and Access Management (IAM) and AWS Security Token Service (STS) to prove the client's identity to a MongoDB server. Briefly, AWS authentication works as follows:
The client uses AWS IAM credentials to create a signature that is sent to the MongoDB server.
The server sends a request to AWS STS using the client's signature.
A successful STS request returns the username (technically, the ARN of the IAM user or role) corresponding to the credentials that the client used. The IAM user ARN is used by the server to look up a defined user, and the client is considered to have authenticated as this user.
Note
Unlike other authentication mechanisms, the username that the application provides when creating a client and the username of the server user are different: the username on the client is the AWS access key ID, but the username on the server is the ARN of the IAM user or role corresponding to the access key ID.
AWS credentials are comprised of:
The access key ID.
The secret access key.
The optional session token.
Authentication with AWS IAM credentials, uses the access key ID and the secret access key. Authentication with temporary AWS IAM credentials uses all three components.
Note
The driver never sends the secret access key or the session token over the network.
Temporary credentials are used with:
STS Assume Role requests.
The Ruby driver allows providing both regular and temporary credentials explicitly as Ruby options or URI options. If credentials are not explicitly provided, the driver will attempt to retrieve them from environment variables described below and from EC2 instance and ECS task metadata endpoints.
Providing Credentials Explicitly
Regular (non-temporary) IAM credentials can be provided as Ruby options, as follows:
client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, user: '<AWS-ACCESS-KEY-ID>', password: '<AWS-SECRET-ACCESS-KEY>', database: 'mydb', )
They can also be provided via a URI:
client = Mongo::Client.new( 'mongodb://<AWS-ACCESS-KEY-ID>:<AWS-SECRET-ACCESS-KEY>@mongodb.example.com/mydb?authMechanism=MONGODB-AWS')
Note
When credentials are provided via a URI, they must be percent-escaped.
To provide temporary credentials, specify the session token in the authentication mechanism properties as follows:
client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, user: '<AWS-ACCESS-KEY-ID>', password: '<AWS-SECRET-ACCESS-KEY>', auth_mech_properties: { aws_session_token: '<AWS-SESSION-TOKEN>', }, database: 'mydb', )
The temporary credentials can also be provided via a URI:
client = Mongo::Client.new( 'mongodb://<AWS-ACCESS-KEY-ID>:<AWS-SECRET-ACCESS-KEY>@mongodb.example.com/mydb?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<AWS-SESSION-TOKEN>')
Automatically Retrieving Credentials
The client can retrieve credentials from the environment or from EC2 or ECS metadata endpoints. To retrieve credentials automatically, specify the AWS authentication mechanism but do not specify a username nor a password:
client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, database: 'mydb', ) # Using a URI: client = Mongo::Client.new( 'mongodb://mongodb.example.com/mydb?authMechanism=MONGODB-AWS')
The driver will try to obtain credentials from the following sources, in the specified order:
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYandAWS_SESSION_TOKENenvironment variables. These environment variables are recognized by a variety of AWS-related libraries and tools such as the official AWS Ruby SDK and the AWS CLI. They are also defined when running in an AWS Lambda environment.The AWS STS AssumeRoleWithWebIdentity action. This returns credentials associated with the service account token. This mechanism requires the following environment variables to be set:
AWS_WEB_IDENTITY_TOKEN_FILE- path to a file containing the service account token.AWS_ROLE_ARN- the Amazon Resource Name (ARN) of the role that the caller is assuming.AWS_ROLE_SESSION_NAME(optional) - An identifier for the assumed role session. If omitted, a random name will be generated by the driver.
The AWS ECS task metadata endpoint. This returns credentials associated with the ECS task role assigned to the container.
The AWS EC2 instance metadata endpoint. This returns credentials associated with the EC2 instance role assigned to the instance.
Note
A credentials source that provides any credentials must provide a complete
set of credentials. For example, the driver will raise an error if only
one of AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY environment
variables is populated but not the other.
Note
If an application is running in an ECS container on an EC2 instance and the container is allowed access to the instance metadata, the driver will attempt to retrieve credentials for the AWS authentication mechanism from the EC2 instance metadata endpoint, thus potentially authenticating as the IAM role assigned to the EC2 instance, if it was not able to retrieve ECS task role credentials from the ECS task endpoint.
LDAP (SASL PLAIN)
Requires MongoDB Enterprise Edition.
MongoDB Enterprise Edition supports the LDAP authentication mechanism which allows you to delegate authentication using a Lightweight Directory Access Protocol LDAP server.
Warning
When using LDAP, passwords are sent to the server in plain text. For this reason, we strongly recommend enabling TLS when using LDAP as your authentication mechanism.
For more information about configuring LDAP authentication in MongoDB, see the SASL/LDAP tutorial in the MongoDB Manual.
client = Mongo::Client.new([ '127.0.0.1:27017' ], auth_mech: :plain, ssl: true, ssl_verify: true, ssl_cert: '/path/to/client.pem', ssl_ca_cert: '/path/to/ca.pem' )
Kerberos (GSSAPI)
Requires MongoDB Enterprise Edition.
To configure the MongoDB server to use Kerberos, please refer to the server Kerberos documentation.
To use the Kerberos authentication mechanism with the Ruby MongoDB driver,
an additional library implementing the Kerberos authenticator -
mongo_kerberos - must be
installed and loaded. To do so, add to your Gemfile:
gem 'mongo', '~> 2' gem 'mongo_kerberos', '~> 2'
... and add to your application code:
require 'mongo' require 'mongo_kerberos'
If using Kerberos authentication with MRI, the password is not specified in driver configuration and it is not sent to the MongoDB server by the driver. Instead a Kerberos session must be established externally to the driver and this session is used by the driver to prove the user's identity to the server. Establishing this session requires that the host system is configured for Kerberos authentication; refer to the Kerberos documentation or your operating system documentation for details. Use the kinit utility to establish a Kerberos session.
If using Kerberos authentication with JRuby, the Kerberos session may
be estabished externally to the driver using the process described above
for MRI; alternatively, the password may be provided directly to the driver
via client configuration, or the path to a keytab file may be provided via
configuration stored in the java.security.auth.login.config system property.
Additionally, the Java runtime environment must be configured for Kerberos;
please refer to the MongoDB Java Driver Kerberos documentation
for more information.
Note
As per the server Kerberos documentation, the FQDN of the host running MongoDB must be specified when using Kerberos authentication.
Note
If using MongoDB URIs, be sure to percent-escape special characters like
/ and @ when they appear in the username.
# Authenticate as appuser@MYREALM: client = Mongo::Client.new("mongodb://appuser%40MYREALM@myserver.mycompany.com:27017/mydb?authMechanism=GSSAPI") # Authenticate as myapp/appuser@MYREALM: client = Mongo::Client.new("mongodb://myapp%2Fappuser%40MYREALM@myserver.mycompany.com:27017/mydb?authMechanism=GSSAPI") # Authenticate using Ruby options: client = Mongo::Client.new(['myserver.mycompany.com:27017'], auth_mech: :gssapi, user: 'myapp/appuser@MYREALM')
MONGODB-CR
Deprecated: MONGODB-CR mechanism is deprecated as of MongoDB 3.6 and removed as of MongoDB 4.0. Please use SCRAM authentication instead.
MONGODB-CR was the default authentication mechanism for MongoDB through version 2.6.
The mechanism can be explicitly set with the credentials:
client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb', user: 'test', password: '123', auth_mech: :mongodb_cr )
Note
If the MongoDB server that the client is connecting to supports SCRAM, the client will attempt to authenticate using SCRAM if no authentication mechanism is explicitly specified. To authenticate to MongoDB 3.0 and higher servers using MONGODB-CR, the MONGODB-CR mechanism must be explicitly requested.