User Management

The Mongo Ruby Driver provides a set of methods for managing users in a MongoDB deployment. All of these methods are defined on the Mongo::Auth::User::View class, which defines the behavior for performing user-related operations on a database. You can access a database’s user view by calling the users method on the correpsonding Mongo::Database object:


Note that this will open a view on the database to which the client is already connected. To interact with the users defined on a different database, call the client’s use method and pass in the name of the database with which you want to connect:


In this example, all operations would be performed on the users database.

For more information about users and user management, see MongoDB’s online documentation.

Users and Databases

When a client connects to the server, MongoDB distinguishes the database that the client will perform operations on from the auth source which is the database storing the user that the client is authenticating as.

In many cases, the auth source is the same as the database. When they differ, user management operations must be done on the auth source database. For example, to create a user authenticating with X.509 certifcate, which must be defined on the $external database:

  'C=US,ST=New York,L=New York City,O=MongoDB,OU=x509,CN=localhost',
  roles: [{role: 'read', db: 'admin'}],

Note that the auth source is not specified for creating the user - auth source is only used during the authentication process. If #create is invoked with a User object with auth_source set, the auth source is ignored for the purposes of user management.

Creating Users

There are two ways to create a new database user with the Ruby Driver.

The simplest way to create a new user is to use the create method, passing in a username, password, and roles:

  password: 'enigma',
  roles: [ Mongo::Auth::Roles::READWRITE ]

Another way to create a user is to first create a Mongo::Auth::User object with all the user information and then pass that object into the create method instead.

user =
  user: 'alanturing',
  password: 'enigma',
  roles: [ Mongo::Auth::Roles::READWRITE ]


Note that your new user’s credentials will be stored in whatever database your client object is currently connected to. This will be your user’s auth_source, and you must be connected to that same database in order to update, remove, or get information about the user you just created in the future.

The create method takes a Hash of options as an optional second argument. The :roles option allows you to grant permissions to the new user. For example, the Mongo::Auth::Roles::READ_WRITE role grants the user the ability to both read from and write to the database in which they were created. Each role can be specified as a String or as a Hash. If you would like to grant permissions to a user on a database other than the one on which they were created, you can pass that database name in the role Hash. To create a user alanturing with permission to read and write on the machines database, you could execute the following code:

  password: 'enigma',
  roles: [{ role: Mongo::Auth::Roles::READWRITE, db: 'machines' }]

For more information about roles in MongoDB, see the Built-in roles documentation.

In addition to the :roles option, the create method supports a :session option, which allows you to specify a Mongo::Session object to use for this operation, as well as a :write_concern option, which specifies the write concern of this operation when performed on a replica set.

User Information

To view information about a user that already exists in the database, use the info method:'alanturing')

If the user exists, this method will return an Array object containing a Hash with information about the user, such as their id, username, the database they were created on, and their roles. If the user doesn’t exist, this method will return an empty Array.

The info method also takes an optional Hash of options as a second argument. Currently, the only supported option is :session, which allows you to specify a Mongo::Session object to use for this operation.

The Ruby Driver does not have a method that lists all of the users that currently exist in a database.

See also


Updating Users

To update a user that already exists in the database, you can use the update method in one of two ways. The first way is to specify the name of the user you wish to update, along with a new set of options.


You must include all user options in the options Hash, even those options whose values will remain the same. Omitting an option is the same as setting it to an empty value.

  roles: [ Mongo::Auth::Roles::READ_WRITE ]
  password: 'turing-test'

The second way to update a user is to pass an updated Mongo::Auth::User object to the update method in lieu of a username.

user ={
  user: 'alanturing',
  roles: [ Mongo::Auth::Roles::READ_WRITE ],
  password: 'turing-test'


Optionally, the update method takes a Hash of options as a second argument. The two possible options for this method are :session, which allows you to specify a Mongo::Session object on which to perform this operation, and :write_concern, which sets a write concern if this operation is performed on a replica set.

Removing Users

To remove a user from the database, use the remove method:


You may pass a Hash of options as a second argument. The two supported options for the remove method are :session and :write_concern. :session allows you to specify a Mongo::Session object to use for this operation. :write_concern specifies the write concern of the operation if you are running this command against a replica set.

The Ruby Driver does not provide a method for removing all users from a database.