db.getRole()

On this page

Definition

Required Access
Examples
Show Role Inheritance Information
Show Role Privileges
Show Authentication Restrictions

Definition

db.getRole(rolename, args)

Returns the roles from which this role inherits privileges. Optionally, the method can also return all the role's privileges.

Run db.getRole() from the database that contains the role. The command can retrieve information for both user-defined roles and built-in roles.

The db.getRole() method accepts the following parameters:

Parameter	Type	Description
`rolename`	string	The name of the role.
`args`	document	Optional. A document specifying additional arguments.

The args document supports the following optional fields:

Field	Type	Description
`showAuthenticationRestrictions`	boolean	Optional. Set this field to `true` to include authentication restrictions in the output. Authentication restrictions indicate the IP addresses that users with this role can connect to and from. By default, this field is `false`, meaning that the `db.getRole()` output does not include authentication restrictions.
`showBuiltinRoles`	boolean	Optional. Set this field to `true` 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.
`showPrivileges`	boolean	Optional. Set this field to `true` to show role privileges, including both privileges inherited from other roles and privileges defined directly. By default, the command returns only the roles from which this role inherits privileges and does not return specific privileges.

db.getRole() wraps the rolesInfo command.

Required Access

To view a role's information, you must be either explicitly granted the role or must have the viewRole action on the role's database.

Examples

The examples in this section show how to use db.getRoles to:

Show Role Inheritance Information
Show Role Privileges
Show Authentication Restrictions

Show Role Inheritance Information

The following operation returns role inheritance information for the role associate defined on the products database:

use products
db.getRole( "associate" )

Example output:

{
  _id: 'products.associate',
  role: 'associate',
  db: 'products',
  roles: [ { role: 'readWrite', db: 'products' } ],
  inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
  isBuiltin: false
}

Show Role Privileges

The following operation returns role inheritance information and privileges for the role associate defined on the products database:

use products
db.getRole( "associate", { showPrivileges: true } )

Example output:

{
  _id: 'products.associate',
  role: 'associate',
  db: 'products',
  privileges: [
    {
      resource: { db: 'products', collection: '' },
      actions: [ 'bypassDocumentValidation' ]
    }
  ],
  roles: [ { role: 'readWrite', db: 'products' } ],
  inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
  inheritedPrivileges: [
    {
      resource: { db: 'products', collection: '' },
      actions: [ 'bypassDocumentValidation' ]
    },
    {
      resource: { db: 'products', collection: '' },
      actions: [
        'changeStream',
        'collStats',
        'compactStructuredEncryptionData',
        'convertToCapped',
        'createCollection',
        'createIndex',
        'dbHash',
        'dbStats',
        'dropCollection',
        'dropIndex',
        'find',
        'insert',
        'killCursors',
        'listCollections',
        'listIndexes',
        'planCacheRead',
        'remove',
        'renameCollectionSameDB',
        'update'
      ]
    }
  ],
  isBuiltin: false
}

Show Authentication Restrictions

The following operation returns role inheritance information and authentication restrictions for the role associate defined on the products database:

use products
db.getRole( "associate", { showAuthenticationRestrictions: true } )

Example output:

{
  _id: 'products.associate',
  role: 'associate',
  db: 'products',
  roles: [ { role: 'readWrite', db: 'products' } ],
  authenticationRestrictions: [
    [ { clientSource: [ '198.51.100.0' ] } ]
  ],
  inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
  inheritedAuthenticationRestrictions: [
    [ { clientSource: [ '198.51.100.0' ] } ]
  ],
  isBuiltin: false
}

Back

db.dropAllRoles

db.getRoles