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.