security-user-defined-roles.txt

.. _user-defined-roles:

==================
User-Defined Roles
==================

.. default-domain:: mongodb

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

.. versionadded:: 2.6

MongoDB provides a number of :doc:`built-in roles
</reference/built-in-roles>`. However, if these roles cannot describe the
desired set of privileges, you can create new roles.

Role Management Interface
-------------------------

To add a role, MongoDB provides the :method:`db.createRole()` method.
MongoDB also provides methods to update existing user-defined roles. For
a full list of role management methods, see
:ref:`role-management-methods`.

Scope
-----

When adding a role, you create the role in a specific database. MongoDB
uses the combination of the database and the role name to uniquely
define a role.

.. include:: /includes/fact-roles-privileges-scope.rst

Centralized Role Data
---------------------

MongoDB stores all role information in the :doc:`system.roles
</reference/system-roles-collection>` collection in the ``admin`` database

Do not access this collection directly but instead use the :ref:`role
management commands <role-management-commands>` to view and edit custom roles.