rolesInfo

Definition

• rolesInfo
• Returns inheritance and privilege information for specified roles,including both user-defined roles andbuilt-in roles.

The rolesInfo command can also retrieve all rolesscoped to a database.

To match a single role on the database, use the following form:

{
  rolesInfo: { role: <name>, db: <db> },
  showPrivileges: <Boolean>,
  showBuiltinRoles: <Boolean>
}

rolesInfo has the following fields:

FieldTypeDescriptionrolesInfostring, document, array, or integerThe role(s) to return information about. For the syntax for specifyingroles, see Behavior.showPrivilegesbooleanOptional. Set the field to true to show role privileges, including both privilegesinherited from other roles and privileges defined directly. By default, thecommand returns only the roles from which this role inherits privileges anddoes not return specific privileges.showBuiltinRolesbooleanOptional. When the rolesInfo field is set to 1, set showBuiltinRoles totrue to include built-in roles in the output.By default this field is set to false, and the output for rolesInfo:1 displays only user-defined roles.

Behavior

Return Information for a Single Role

To specify a role from the current database, specify the role by its name:

{ rolesInfo: "<rolename>" }

To specify a role from another database, specify the role by a document thatspecifies the role and database:

{ rolesInfo: { role: "<rolename>", db: "<database>" } }

Return Information for Multiple Roles

To specify multiple roles, use an array. Specify each role in the array as adocument or string. Use a string only if the role exists on the database onwhich the command runs:

{
  rolesInfo: [
     "<rolename>",
     { role: "<rolename>", db: "<database>" },
     ...
  ]
}

Return Information for All Roles in the Database

To specify all roles in the database on which the command runs, specifyrolesInfo: 1. By default MongoDB displays all the user-defined roles in the database. To include built-in roles as well, include the parameter-value pairshowBuiltinRoles: true:

{ rolesInfo: 1, showBuiltinRoles: true }

Required Access

To view a role’s information, you must be either explicitly granted therole or must have the viewRoleaction on the role’s database.

Output

• rolesInfo.role
• The name of the role.

• rolesInfo.db
• The database on which the role is defined. Every database has built-inroles. A database might also have user-definedroles.

• rolesInfo.isBuiltin
• A value of true indicates the role is a built-in role. A value of false indicates the role is auser-defined role.

• rolesInfo.roles
• The roles that directly provide privileges to this role and the databaseson which the roles are defined.

• rolesInfo.inheritedRoles
• All roles from which this role inherits privileges. This includes the rolesin the rolesInfo.roles array as well as the roles from which theroles in the rolesInfo.roles array inherit privileges. Allprivileges apply to the current role. The documents in this field list theroles and the databases on which they are defined.

• rolesInfo.privileges
• The privileges directly specified by this role; i.e. the arrayexcludes privileges inherited from other roles. By default theoutput does not include the privileges field. Toinclude the field, specify showPrivileges: true when running therolesInfo command.

Each privilege document specifies the resources and the actions allowed on the resources.

• rolesInfo.inheritedPrivileges
• All privileges granted by this role, including those inherited fromother roles. By default the output does not include theinheritedPrivileges field. To include the field,specify showPrivileges: true when running therolesInfo command.

Each privilege document specifies the resources and the actions allowed on the resources.

Examples

View Information for a Single Role

The following command returns the role inheritance information for therole associate defined in the products database:

db.runCommand(
    {
      rolesInfo: { role: "associate", db: "products" }
    }
)

The following command returns the role inheritance information for the rolesiteManager on the database on which the command runs:

db.runCommand(
    {
      rolesInfo: "siteManager"
    }
)

The following command returns both the role inheritance and the privilegesfor the role associate defined on the products database:

db.runCommand(
    {
      rolesInfo: { role: "associate", db: "products" },
      showPrivileges: true
    }
)

View Information for Several Roles

The following command returns information for two roles on two differentdatabases:

db.runCommand(
    {
      rolesInfo: [
         { role: "associate", db: "products" },
         { role: "manager", db: "resources" }
      ]
    }
)

The following returns both the role inheritance and the privileges:

db.runCommand(
    {
      rolesInfo: [
         { role: "associate", db: "products" },
         { role: "manager", db: "resources" }
      ],
      showPrivileges: true
    }
)

View All User-Defined Roles for a Database

The following operation returns all user-defined roles on the database on which the command runs and includesprivileges:

db.runCommand(
    {
      rolesInfo: 1,
      showPrivileges: true
    }
)

View All User-Defined and Built-In Roles for a Database

The following operation returns all roles on the database on which the commandruns, including both built-in and user-defined roles:

db.runCommand(
    {
      rolesInfo: 1,
      showBuiltinRoles: true
    }
)