system.roles Collection

New in version 2.6.

The system.roles collection in the admin database stores theuser-defined roles. To create and manage these user-definedroles, MongoDB provides role management commands.

system.roles Schema

The documents in the system.roles collection have the followingschema:

{
  _id: <system-defined id>,
  role: "<role name>",
  db: "<database>",
  privileges:
      [
          {
              resource: { <resource> },
              actions: [ "<action>", ... ]
          },
          ...
      ],
  roles:
      [
          { role: "<role name>", db: "<database>" },
          ...
      ]
}

A system.roles document has the following fields:

• admin.system.roles.role
• The role field is a string thatspecifies the name of the role.

• admin.system.roles.db
• The db field is a string that specifiesthe database to which the role belongs. MongoDB uniquely identifieseach role by the pairing of its name (i.e.role) and its database.

• admin.system.roles.privileges
• The privileges array contains theprivilege documents that define the privileges for the role.

A privilege document has the following syntax:

{
  resource: { <resource> },
  actions: [ "<action>", ... ]
}

Each privilege document has the following fields:

• admin.system.roles.privileges[n].resource
• A document that specifies the resources upon which the privilegeactions apply. The documenthas one of the following form:

{ db: <database>, collection: <collection> }

or

{ cluster : true }

See Resource Document for more details.

• admin.system.roles.privileges[n].actions
• An array of actions permitted on the resource. For a list ofactions, see Privilege Actions.

• admin.system.roles.roles
• The roles array contains role documentsthat specify the roles from which this role inherits privileges.

A role document has the following syntax:

{ role: "<role name>", db: "<database>" }

A role document has the following fields:

• admin.system.roles.roles[n].role

• The name of the role. A role can be a built-in role provided by MongoDB or a user-definedrole.

• admin.system.roles.roles[n].db

• The name of the database where the role is defined.

Examples

Consider the following sample documents found in system.rolescollection of the admin database.

A User-Defined Role Specifies Privileges

The following is a sample document for a user-defined role appUserdefined for the myApp database:

{
  _id: "myApp.appUser",
  role: "appUser",
  db: "myApp",
  privileges: [
       { resource: { db: "myApp" , collection: "" },
         actions: [ "find", "createCollection", "dbStats", "collStats" ] },
       { resource: { db: "myApp", collection: "logs" },
         actions: [ "insert" ] },
       { resource: { db: "myApp", collection: "data" },
         actions: [ "insert", "update", "remove", "compact" ] },
       { resource: { db: "myApp", collection: "system.js" },
         actions: [ "find" ] },
  ],
  roles: []
}

The privileges array lists the five privileges that the appUserrole specifies:

• The first privilege permits its actions ( "find","createCollection", "dbStats", "collStats") on all thecollections in the myApp database excluding its systemcollections. See Specify a Database as Resource.
• The next two privileges permits additional actions on specificcollections, logs and data, in the myApp database. SeeSpecify a Collection of a Database as Resource.
• The last privilege permits actions on one systemcollections in the myAppdatabase. While the first privilege gives database-wide permissionfor the find action, the action does not apply to myApp’ssystem collections. To give access to a system collection, aprivilege must explicitly specify the collection. SeeResource Document.

As indicated by the empty roles array, appUser inherits noadditional privileges from other roles.

User-Defined Role Inherits from Other Roles

The following is a sample document for a user-defined role appAdmindefined for the myApp database: The document shows that theappAdmin role specifies privileges as well as inherits privilegesfrom other roles:

{
  _id: "myApp.appAdmin",
  role: "appAdmin",
  db: "myApp",
  privileges: [
      {
         resource: { db: "myApp", collection: "" },
         actions: [ "insert", "dbStats", "collStats", "compact" ]
      }
  ],
  roles: [
      { role: "appUser", db: "myApp" }
  ]
}

The privileges array lists the privileges that the appAdminrole specifies. This role has a single privilege that permits itsactions ( "insert", "dbStats", "collStats", "compact")on all the collections in the myApp database excluding its systemcollections. See Specify a Database as Resource.

The roles array lists the roles, identified by the role names anddatabases, from which the role appAdmin inherits privileges.