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:
client.database.users
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:
client.use(:users).database.users
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:
client.use('$external').database.users.create( '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:
client.database.users.create( 'alanturing', 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 = Mongo::User.new( user: 'alanturing', password: 'enigma', roles: [ Mongo::Auth::Roles::READWRITE ] ) client.database.users.create(user)
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:
client.database.users.create( 'alanturing', 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.
Tip
See also:
User Information
To view information about a user that already exists in the database, use the
info method:
client.database.users.info('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.
Tip
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.
Warning
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.
client.database.users.update( 'alanturing', 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 = Mongo::Auth::User.new({ user: 'alanturing', roles: [ Mongo::Auth::Roles::READ_WRITE ], password: 'turing-test' }) client.database.users.update(user)
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.
Tip
See also:
Removing Users
To remove a user from the database, use the remove method:
client.database.users.remove('alanturing')
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.