************** Authentication ************** .. default-domain:: mongodb .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol MongoDB supports a variety of :manual:`authentication mechanisms `. For more information about configuring your MongoDB server for each of these authentication mechanisms see MongoDB's :manual:`online documentation `. For more information about users and the Ruby driver's helpers for user management, see the :ref:`User Management tutorial`. Providing credentials ===================== If authentication is enabled, provide credentials when creating a new client: .. code-block:: ruby 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: .. code-block:: ruby authenticated_client = client.with( user: 'another-user', password: '123' ) It is also possible to change the client's database and credentials in one step: .. code-block:: ruby authenticated_music_client = client.with( database: 'music', user:'test', password:'123' ) .. _auth-source: 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: .. code-block:: ruby 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: .. code-block:: ruby 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 ````` :manual:`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: .. code-block:: ruby 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: .. code-block:: ruby 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") .. _x.509: Client Certificate (X.509) `````````````````````````` The driver presents an X.509 certificate during TLS negotiation. The MONGODB-X509 authentication mechanism authenticates a username derived from the distinguished subject name of this certificate. 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 :manual:`X.509 tutorial in the MongoDB Manual `. .. code-block:: ruby 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-auth: 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: 1. The client uses AWS IAM credentials to create a signature that is sent to the MongoDB server. 2. The server sends a request to AWS STS using the client's signature. 3. 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. - `EC2 instance roles `_. - `ECS task roles `_. - `AWS Lambda environment `_. 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: .. code-block:: ruby client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, user: '', password: '', database: 'mydb', ) They can also be provided via a URI: .. code-block:: ruby client = Mongo::Client.new( 'mongodb://:@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: .. code-block:: ruby client = Mongo::Client.new(['mongodb.example.com'], auth_mech: :aws, user: '', password: '', auth_mech_properties: { aws_session_token: '', }, database: 'mydb', ) The temporary credentials can also be provided via a URI: .. code-block:: ruby client = Mongo::Client.new( 'mongodb://:@mongodb.example.com/mydb?authMechanism=MONGODB-AWS&authMechanismProperties=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: .. code-block:: ruby 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_KEY`` and ``AWS_SESSION_TOKEN`` environment 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 `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. .. _plain: 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 :manual:`SASL/LDAP tutorial in the MongoDB Manual `. .. code-block:: ruby 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: Kerberos (GSSAPI) ````````````````` *Requires MongoDB Enterprise Edition.* To configure the MongoDB server to use Kerberos, please refer to the :manual:`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``: .. code-block:: ruby gem 'mongo', '~> 2' gem 'mongo_kerberos', '~> 2' ... and add to your application code: .. code-block:: ruby 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. .. code-block:: ruby # 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 <#scram>`_ instead. MONGODB-CR was the default authentication mechanism for MongoDB through version 2.6. The mechanism can be explicitly set with the credentials: .. code-block:: ruby 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.