Database Manual / Reference / Database Commands / Role Management

rolesInfo (database command数据库命令)

Definition定义

rolesInfo

Returns inheritance and privilege information for specified roles, including both user-defined roles and built-in roles.返回指定角色的继承和权限信息，包括用户定义的角色和内置角色。

The rolesInfo command can also retrieve all roles scoped to a database.rolesInfo命令还可以检索数据库范围内的所有角色。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务

Note

This command is supported in all MongoDB Atlas clusters. 所有MongoDB Atlas集群都支持此命令。For information on Atlas support for all commands, see Unsupported Commands.有关Atlas支持所有命令的信息，请参阅不支持的命令。

  • MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
  • MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The command has the following syntax:该命令具有以下语法：

db.runCommand(
   {
     rolesInfo: { role: <name>, db: <db> },
     showAuthenticationRestrictions: <Boolean>,
     showBuiltinRoles: <Boolean>,
     showPrivileges: <Boolean>,
     comment: <any>
   }
)

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Field字段Type类型Description描述
rolesInfostring, document, array, or integer字符串、文档、数组或整数The role(s) to return information about. For the syntax for specifying roles, see Behavior.要返回有关信息的角色。有关指定角色的语法，请参阅行为。
showAuthenticationRestrictionsboolean布尔值

Optional. 可选。Set this field to true to include authentication restrictions in the output. 将此字段设置为true，以便在输出中包含身份验证限制。Authentication restrictions indicate the IP addresses that users with this role can connect to and from.身份验证限制表示具有此角色的用户可以连接到和从中连接的IP地址。

By default, this field is false, meaning that the rolesInfo output does not include authentication restrictions.默认情况下，此字段为false，这意味着rolesInfo输出不包括身份验证限制。

showBuiltinRolesboolean布尔值Optional. 可选。When the rolesInfo field is set to 1, set showBuiltinRoles to true to include built-in roles in the output. 当rolesInfo字段设置为1时，将showBuiltinRoles设置为true以在输出中包含内置角色。By default, this field is set to false, and the output for rolesInfo: 1 displays only user-defined roles.默认情况下，此字段设置为false，rolesInfo:1的输出仅显示用户定义的角色。
showPrivilegesboolean布尔值Optional. 可选。Set the field to true to show role privileges, including both privileges inherited from other roles and privileges defined directly. 将该字段设置为true以显示角色权限，包括从其他角色继承的权限和直接定义的权限。By default, the command returns only the roles from which this role inherits privileges and does not return specific privileges.默认情况下，该命令仅返回此角色继承权限的角色，不返回特定权限。
commentany任意

Optional. 可选。A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:用户提供了要附加到此命令的注释。设置后，此注释将与此命令的记录一起出现在以下位置：

A comment can be any valid BSON type (string, integer, object, array, etc).注释可以是任何有效的BSON类型（字符串、整数、对象、数组等）。

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 that specifies 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 a document or string. Use a string only if the role exists on the database on which 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, specify rolesInfo: 1. By default MongoDB displays all the user-defined roles in the database. 要指定运行该命令的数据库中的所有角色，请指定rolesInfo:1。默认情况下，MongoDB显示数据库中所有用户定义的角色。To include built-in roles as well, include the parameter-value pair showBuiltinRoles: true:要同时包含内置角色，请包含参数值对showBuiltinRoles:true：

{ rolesInfo: 1, showBuiltinRoles: true }

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.要查看角色的信息，您必须被明确授予该角色，或者必须对该角色的数据库执行viewRole操作。

Output输出

rolesInfo.role
The name of the role.角色的名称。
rolesInfo.db
The database on which the role is defined. 定义角色的数据库。Every database has built-in roles. A database might also have user-defined roles.每个数据库都有内置的角色。数据库也可能具有用户定义的角色。
rolesInfo.isBuiltin
A value of true indicates the role is a built-in role. 值为true表示该角色是内置角色。A value of false indicates the role is a user-defined role.值false表示该角色是用户定义的角色。
rolesInfo.roles
The roles that directly provide privileges to this role and the databases on which the roles are defined.直接为此角色提供权限的角色以及定义这些角色的数据库。
rolesInfo.inheritedRoles
All roles from which this role inherits privileges. This includes the roles in the rolesInfo.roles array as well as the roles from which the roles in the rolesInfo.roles array inherit privileges. 此角色继承权限的所有角色。这包括rolesInfo.roles数组中的角色以及rolesInfo.roles数组中角色从中继承权限的角色。All privileges apply to the current role. The documents in this field list the roles and the databases on which they are defined.所有权限都适用于当前角色。此字段中的文档列出了角色及其定义的数据库。
rolesInfo.privileges

The privileges directly specified by this role; i.e. the array excludes privileges inherited from other roles. By default the output does not include the privileges field. 此角色直接指定的权限；即，数组不包括从其他角色继承的权限。默认情况下，输出不包括privileges字段。To include the field, specify showPrivileges: true when running the rolesInfo command.要包含该字段，请在运行rolesInfo命令时指定showPrivileges:true。

Each privilege document specifies the resources and the actions allowed on the resources.每个权限文档都指定了资源和允许对资源执行的操作。

rolesInfo.inheritedPrivileges

All privileges granted by this role, including those inherited from other roles. By default the output does not include the inheritedPrivileges field. 此角色授予的所有权限，包括从其他角色继承的权限。默认情况下，输出不包括inheritedPrivileges字段。To include the field, specify showPrivileges: true when running the rolesInfo command.要包含该字段，请在运行rolesInfo命令时指定showPrivileges: true。

Each privilege document specifies the resources and the actions allowed on the resources.每个权限文档都指定了资源和允许对资源执行的操作。

Examples示例

The examples in this section show how to use the rolesInfo command to:本节中的示例显示了如何使用rolesInfo命令：

View Information for a Single Role查看单个角色的信息

The following command returns the role inheritance information for the role associate defined in the products database:以下命令返回products数据库中定义的角色associate的角色继承信息：

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

The following command returns the role inheritance information for the role siteManager on the database on which the command runs:以下命令返回运行该命令的数据库上角色siteManager的角色继承信息：

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

The following command returns both the role inheritance and the privileges for the role associate defined on the products database:以下命令返回在products数据库上定义的角色associate的角色继承和权限：

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

View Information for Multiple Roles查看多个角色的信息

The following command returns information for two roles on two different databases:以下命令返回两个不同数据库上两个角色的信息：

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 includes privileges:以下操作返回运行该命令的数据库上的所有用户定义角色，并包括权限：

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

Example output (shortened for readability):示例输出（为便于阅读而缩短）：

{
  roles: [
    {
      _id: 'products.associate',
      role: 'associate',
      db: 'products',
      privileges: [
        {
          resource: { db: 'products', collection: '' },
          actions: [ 'bypassDocumentValidation' ]
        }
      ],
      roles: [ { role: 'readWrite', db: 'products' } ],
      isBuiltin: false,
      inheritedRoles: [ { role: 'readWrite', db: 'products' } ],
      inheritedPrivileges: [
        {
          resource: { db: 'products', collection: '' },
          actions: [ 'bypassDocumentValidation' ]
        },
        {
          resource: { db: 'products', collection: '' },
          actions: [
            'changeStream',
            'collStats',
            'compactStructuredEncryptionData',
            ...
          ]
        },
        ...
      ]
    }
  ],
  ok: 1
}

View All User-Defined and Built-In Roles for a Database查看数据库的所有用户定义和内置角色

The following operation returns all roles on the database on which the command runs, including both built-in and user-defined roles:以下操作返回运行该命令的数据库上的所有角色，包括内置和用户定义的角色：

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

Example output (shortened for readability):示例输出（为便于阅读而缩短）：

{
  roles: [
    {
      role: 'enableSharding',
      db: 'products',
      isBuiltin: true,
      roles: [],
      inheritedRoles: []
    },
    {
      role: 'userAdmin',
      db: 'products',
      isBuiltin: true,
      roles: [],
      inheritedRoles: []
    },
    {
      role: 'read',
      db: 'products',
      isBuiltin: true,
      roles: [],
      inheritedRoles: []
    },
    ...
  ],
  ok: 1
}

View Authentication Restrictions for Roles查看角色的身份验证限制

The following operation returns all user-defined roles on the products database and includes authentication restrictions:以下操作返回products数据库上的所有用户定义角色，并包括身份验证限制：

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

Example output:示例输出：

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