createRole（数据库命令）

定义

createRole: Creates a role and specifies its privileges. The role applies to the database on which you run the command. The createRole command returns a duplicate role error if the role already exists in the database.
提示
In mongosh, this command can also be run through the db.createRole() helper method.
Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

重要

This command is not supported in MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

语法

该命令具有以下语法：

db.adminCommand(
   {
     createRole: "<new role>",
     privileges: [
       { resource: { <resource> }, actions: [ "<action>", ... ] },
       ...
     ],
     roles: [
       { role: "<role>", db: "<database>" } | "<role>",
       ...
     ],
     authenticationRestrictions: [
       {
         clientSource: ["<IP>" | "<CIDR range>", ...],
         serverAddress: ["<IP>" | "<CIDR range>", ...]
       },
       ...
     ],
     writeConcern: <write concern document>,
     comment: <any>
   }
)

命令字段

The createRole command has the following fields:

字段	类型	说明
`createRole`	字符串	新角色的名称。
`privileges`	阵列	授予角色的权限。权限由资源和允许的操作组成。有关权限的语法，请参阅 `privileges` 数组。必须包含 `privileges` 字段。使用空数组指定无权限。
`roles`	阵列	该角色所继承权限的源角色的数组。必须包含 `roles` 字段。使用空数组指定没有可从其继承权限的角色。
`authenticationRestrictions`	阵列	可选。服务器对角色实施的身份验证限制。指定允许授予此角色的用户连接到和/或可以从中进行连接的 IP 地址和 CIDR 范围列表。
`writeConcern`	文档	可选。操作的写关注级别。请参阅写关注规范。
`comment`	any	可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置： mongod 日志消息，位于 `attr.command.cursor.comment` 字段中。 `command.comment` 字段中的数据库分析器输出。 `currentOp` 输出，在 `command.comment` 字段。注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

角色

在 roles 字段中，可以指定内置角色和用户自定义角色。

To specify a role that exists in the same database where createRole runs, you can either specify the role with the name of the role:

"readWrite"

或者，可以使用文档指定角色，如下所示：

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

要指定存在于其他数据库中的角色，请使用文档指定该角色。

authenticationRestrictions

authenticationRestrictions 文档只能包含以下字段。如果 authenticationRestrictions 文档包含无法识别的字段，服务器会引发错误：

字段名称	值	说明
`clientSource`	IP 地址和/或 CIDR 范围的数组	如果存在，则在对用户进行身份验证时，服务器会验证客户端的 IP 地址是否在给定列表中或属于列表中的 CIDR 范围。如果客户端的 IP 地址不存在，服务器不会对用户进行身份验证。
`serverAddress`	IP 地址和/或 CIDR 范围的数组	客户端可以连接的 IP 地址或 CIDR 范围列表。如果存在，服务器将验证客户端的连接是否已通过给定列表中的 IP 地址接受。如果通过无法识别的 IP 地址接受连接，服务器不会对用户进行身份验证。

重要

如果用户继承的多个角色具有不兼容的身份验证限制，则该用户将不可用。

例如，如果用户继承了一个角色（其中 clientSource 字段为 ["198.51.100.0"]）和另一个角色（其中 clientSource 字段为 ["203.0.113.0"]），则服务器无法对该用户进行身份验证。

有关MongoDB中身份身份验证的更多信息，请参阅自托管部署上的身份验证。

行为

角色的权限适用于创建该角色的数据库。该角色可以从其数据库中的其他角色继承权限。在 admin 数据库上创建的角色可以包含适用于所有数据库或集群的权限，并且可以从其他数据库中的角色继承权限。

必需的访问权限

要在数据库中创建角色，必须：

对该数据库资源执行 createRole 操作。
对该数据库执行 grantRole 操作，用于为新角色指定权限以及指定要从其继承权限的角色。

通过内置角色 userAdmin 和 userAdminAnyDatabase，可在各自的资源上执行 createRole 和 grantRole 操作。

要在指定 authenticationRestrictions 时创建角色，必须针对创建该角色的数据库资源执行 setAuthenticationRestriction 操作。

例子

The following createRole command creates the myClusterwideAdmin role on the admin database:

db.adminCommand({ createRole: "myClusterwideAdmin",
  privileges: [
    { resource: { cluster: true }, actions: [ "addShard" ] },
    { resource: { db: "config", collection: "" }, actions: [ "find", "update", "insert", "remove" ] },
    { resource: { db: "users", collection: "usersCollection" }, actions: [ "update", "insert", "remove" ] },
    { resource: { db: "", collection: "" }, actions: [ "find" ] }
  ],
  roles: [
    { role: "read", db: "admin" }
  ],
  writeConcern: { w: "majority" , wtimeout: 5000 }
})