Authentication¶

On this page

Providing credentials
Auth Source
MONGODB-CR Mechanism
Client Certificate (X.509)
LDAP (SASL PLAIN) mechanism
Kerberos (GSSAPI) mechanism

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 user management, see the User Management tutorial.

Providing credentials¶

If authentication is enabled, provide credentials when creating a new client.

copy

client = Mongo::Client.new([ '127.0.0.1:27017' ],
                           user: 'test',
                           password: '123' )

The current database can be changed with the client’s use method.

copy

client = Mongo::Client.new([ '127.0.0.1:27017' ])
music_client = client.use( 'music')

A new client can be created with the authentication credentials.

copy

authenticated_client = client.with( user: 'test',
                                   password: '123' )

Alternatively, setting the current database and credentials can be done in one step:

copy

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.

When creating a client with authentication credentials, you may specify an auth source for the user:

copy

client = Mongo::Client.new([ '127.0.0.1:27017' ],
                           user: 'test',
                           password: '123',
                           auth_source: '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 becomes 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, $external is used as the auth source. For the GSSAPI and MONGODB_X509 mechanisms, the auth source is always $external.

MONGODB-CR Mechanism¶

Deprecated: MONGODB-CR mechanism is deprecated as of MongoDB version 3.6. Please use SCRAM authentication instead.

MONGODB-CR was the default authentication mechanism for MongoDB up through version 2.6.

The mechanism can be explicitly set with the credentials:

copy

client = Mongo::Client.new([ '127.0.0.1:27017' ],
                           :database => 'music',
                           user: 'test',
                           password: '123',
                           auth_mech: :mongodb_cr )

Client Certificate (X.509)¶

The driver presents an X.509 certificate during SSL 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 SSL connections with certificate validation.

To authenticate the client, you will need a valid SSL 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.

copy

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' )

LDAP (SASL PLAIN) mechanism¶

Requires MongoDB Enterprise Edition v2.6 or greater.

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

copy

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) mechanism¶

Requires MongoDB Enterprise Edition v2.4 or greater.

MongoDB Enterprise Edition v2.4+ supports Kerberos authentication.

To use Kerberos authentication from Ruby, mongo_kerberos must be installed. Add to your Gemfile:

copy

gem 'mongo'
gem 'mongo_kerberos'

… and in your application:

copy

require 'mongo'
require 'mongo_kerberos'

To use Kerberos in the Ruby driver with MRI, create a ticket-granting ticket using kinit. See this documentation for more information.

To use Kerberos in the Ruby driver with JRuby, do the following:

Specify several system properties so that the underlying GSSAPI Java libraries can acquire a Kerberos ticket. See the MongoDB Java Driver authentication documentation for more information.
Either provide a password OR set the ‘java.security.auth.login.config’ system property to a config file that references a keytab file.

For more information about deploying MongoDB with Kerberos authentication, see the manual.

copy

client = Mongo::Client.new([ '127.0.0.1:27017' ],
                           auth_mech: :gssapi,
                           user: 'test',
                           password: '123' )

← Creating a Client User Management →