.. _user-management:

***************
User Management
***************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

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:

.. code-block:: ruby

  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:

.. code-block:: ruby

  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
:manual:`online documentation </core/security-users>`.


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 <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:

.. code-block:: ruby

  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:

.. code-block:: ruby

  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.

.. code-block:: ruby

  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:

.. code-block:: ruby

  client.database.users.create(
    'alanturing',
    password: 'enigma',
    roles: [{ role: Mongo::Auth::Roles::READWRITE, db: 'machines' }]
  )

For more information about roles in MongoDB, see the
:manual:`Built-in roles</reference/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.

.. seealso::
  :manual:`Built-in roles</reference/built-in-roles/>`
  :manual:`Write Concerns</core/replica-set-write-concern/>`,
  :ref:`Sessions<sessions>`,


User Information
================

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

.. code-block:: ruby

  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.

.. seealso::
  :ref:`Sessions <sessions>`


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.

.. code-block:: ruby

  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.

.. code-block:: ruby

  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.

.. seealso::
  :ref:`Sessions<sessions>`
  :manual:`Write Concerns</core/replica-set-write-concern/>`,

Removing Users
==============

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

.. code-block:: ruby

  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.

.. seealso::
  :ref:`Sessions<sessions>`
  :manual:`Write Concerns</core/replica-set-write-concern/>`,