Database Manual / Reference / Database Commands / User Management

createUser (database command)（数据库命令）

Definition定义

createUser

Creates a new user on the database where you run the command. The createUser command returns a duplicate user error if the user exists.在运行命令的数据库上创建新用户。如果用户存在，createUser命令将返回重复用户错误。

Tip

In mongosh, this command can also be run through the db.createUser() helper method.在mongosh中，此命令也可以通过db.createUser()辅助方法运行。

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.助手方法对mongosh用户来说很方便，但它们可能不会返回与数据库命令相同级别的信息。如果不需要便利性或需要额外的返回字段，请使用database命令。

Compatibility兼容性

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

  • 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的源代码可用、免费使用和自我管理版本

Important

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

Syntax语法

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

Tip

You can use the passwordPrompt() method in conjunction with various user authentication management methods and commands to prompt for the password instead of specifying the password directly in the method or command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.您可以将passwordPrompt()方法与各种用户身份验证管理方法和命令结合使用，以提示输入密码，而不是直接在方法或命令调用中指定密码。但是，您仍然可以像使用早期版本的mongo shell一样直接指定密码。

db.runCommand(
   {
     createUser: "<name>",
     pwd: passwordPrompt(),      // Or  "<cleartext password>"
     customData: { <any information> },
     roles: [
       { role: "<role>", db: "<database>" } | "<role>",
       ...
     ],
     writeConcern: { <write concern> },
     authenticationRestrictions: [
        { clientSource: [ "<IP|CIDR range>", ... ], serverAddress: [ "<IP|CIDR range>", ... ] },
        ...
     ],
     mechanisms: [ "<scram-mechanism>", ... ],
     digestPassword: <boolean>,
     comment: <any>
   }
)

Command Fields命令字段

createUser has the following fields:具有以下字段：

Field字段Type类型Description描述
createUserstring字符串The name of the new user.新用户的名称。
pwdstring字符串

The user's password. The pwd field is not required if you run createUser on the $external database to create users who have credentials stored externally to MongoDB.用户的密码。如果在$external数据库上运行createUser以创建具有存储在MongoDB外部的凭据的用户，则不需要pwd字段。

The value can be either:该值可以是：

  • The user's password in cleartext string明文字符串形式的用户密码
  • passwordPrompt(), to prompt for the user's password，提示输入用户密码

You can use the passwordPrompt() method in conjunction with various user authentication management methods and commands to prompt for the password instead of specifying the password directly in the method or command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.您可以将passwordPrompt()方法与各种用户身份验证管理方法和命令结合使用，以提示输入密码，而不是直接在方法或命令调用中指定密码。但是，您仍然可以像使用早期版本的mongo shell一样直接指定密码。

customDatadocument文档Optional. 可选。Any arbitrary information. This field can be used to store any data an admin wishes to associate with this particular user. For example, this could be the user's full name or employee id.任何任意信息。此字段可用于存储管理员希望与此特定用户关联的任何数据。例如，这可能是用户的全名或员工id。
rolesarray数组The roles granted to the user. Can specify an empty array [] to create users without roles.授予用户的角色。可以指定一个空数组[]来创建没有角色的用户。
digestPasswordboolean布尔值

Optional. 可选。Indicates whether the server or the client digests the password.指示是服务器还是客户端对密码进行摘要。

If true, the server receives undigested password from the client and digests the password.如果为真，服务器将从客户端接收未消化的密码并对密码进行摘要。

If false, the client digests the password and passes the digested password to the server. Not compatible with SCRAM-SHA-256如果为false，客户端将解析密码并将解析后的密码传递给服务器。与SCRAM-SHA-256不兼容

The default value is true.默认值为true。

writeConcerndocument文档Optional. 可选。The level of write concern for the operation. See Write Concern Specification.操作的写入关注级别。请参阅写入关注规范。
authenticationRestrictionsarray数组Optional. 可选。The authentication restrictions the server enforces on the created user. Specifies a list of IP addresses and CIDR ranges from which the user is allowed to connect to the server or from which the server can accept users.服务器对创建的用户实施的身份验证限制。指定允许用户连接到服务器或服务器可以接受用户的IP地址和CIDR范围的列表。
mechanismsarray数组

Optional. 可选。Specify the specific SCRAM mechanism or mechanisms for creating SCRAM user credentials. If authenticationMechanisms is specified, you can only specify a subset of the authenticationMechanisms.指定创建SCRAM用户凭据的特定SCRAM机制。如果指定了authenticationMechanisms，则只能指定authenticationMechanisms的一个子集。

Valid values are:有效值为：

  • "SCRAM-SHA-1"
  • Uses the SHA-1 hashing function.使用SHA-1哈希函数。
  • "SCRAM-SHA-256"
  • Uses the SHA-256 hashing function.使用SHA-256哈希函数。
  • Requires featureCompatibilityVersion set to 4.0.需要将功能兼容性版本设置为4.0。
  • Requires digestPassword to be true.要求digestPassword为true。

The default for featureCompatibilityVersion is 4.0 is both SCRAM-SHA-1 and SCRAM-SHA-256.featureCompatibilityVersion的默认值为4.0，即SCRAM-SHA-1和SCRAM-SHA-256。

The default for featureCompatibilityVersion is 3.6 is SCRAM-SHA-1.featureCompatibilityVersion的默认值为3.6，即SCRAM-SHA-1。

digestPasswordboolean布尔值

Optional. 可选。Indicates whether the server or the client digests the password.指示是服务器还是客户端对密码进行摘要。

If true, the server receives undigested password from the client and digests the password.如果为真，服务器将从客户端接收未消化的密码并对密码进行摘要。

If false, the client digests the password and passes the digested password to the server. Not compatible with SCRAM-SHA-256如果为false，客户端将解析密码并将解析后的密码传递给服务器。与SCRAM-SHA-256不兼容

The default value is true.默认值为true。

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类型（字符串、整数、对象、数组等）。

Roles角色

In the roles field, you can specify both built-in roles and user-defined roles.在角色字段中，您可以指定内置角色和用户定义的角色。

To specify a role that exists in the same database where createUser runs, you can either specify the role with the name of the role:要指定存在于运行createUser的同一数据库中的角色，您可以使用角色的名称指定角色：

"readWrite"

Or you can specify the role with a document, as in:或者，您可以在文档中指定角色，如：

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

To specify a role that exists in a different database, specify the role with a document.若要指定存在于其他数据库中的角色，请使用文档指定该角色。

Authentication Restrictions身份验证限制

The authenticationRestrictions document can contain only the following fields. The server throws an error if the authenticationRestrictions document contains an unrecognized field:authenticationRestrictions文档只能包含以下字段。如果authenticationRestrictions文档包含无法识别的字段，服务器将抛出错误：

Field Name字段名称Value值Description描述
clientSourceArray of IP addresses and/or CIDR rangesIP地址和/或CIDR范围数组If present, when authenticating a user, the server verifies that the client's IP address is either in the given list or belongs to a CIDR range in the list. If the client's IP address is not present, the server does not authenticate the user.如果存在，在对用户进行身份验证时，服务器会验证客户端的IP地址是否在给定列表中或属于列表中的CIDR范围。如果客户端的IP地址不存在，则服务器不会对用户进行身份验证。
serverAddressArray of IP addresses and/or CIDR rangesIP地址和/或CIDR范围数组A list of IP addresses or CIDR ranges to which the client can connect. If present, the server will verify that the client's connection was accepted via an IP address in the given list. 客户端可以连接的IP地址或CIDR范围列表。如果存在，服务器将验证客户端的连接是否通过给定列表中的IP地址被接受。If the connection was accepted via an unrecognized IP address, the server does not authenticate the user.如果通过无法识别的IP地址接受连接，则服务器不会对用户进行身份验证。

Important

If a user inherits multiple roles with incompatible authentication restrictions, that user becomes unusable.如果用户继承了多个身份验证限制不兼容的角色，则该用户将无法使用。

For example, if a user inherits one role in which the clientSource field is ["198.51.100.0"] and another role in which the clientSource field is ["203.0.113.0"] the server is unable to authenticate the user.例如，如果用户继承了一个角色，其中clientSource字段为["198.51.100.0"]，另一个角色的clientSource字段是["203.0.113.0"]，则服务器无法对用户进行身份验证。

For more information on authentication in MongoDB, see Authentication on Self-Managed Deployments.有关MongoDB中身份验证的更多信息，请参阅自我管理部署的身份验证。

Behavior行为

User ID用户ID

MongoDB automatically assigns a unique userId to the user upon creation.MongoDB在创建时会自动为用户分配一个唯一的用户ID。

Encryption加密

Warning

By default, createUser sends all specified data to the MongoDB instance in cleartext, even if using passwordPrompt(). 默认情况下，即使使用passwordPrompt()，createUser也会以明文形式将所有指定的数据发送到MongoDB实例。Use TLS transport encryption to protect communications between clients and the server, including the password sent by createUser. 使用TLS传输加密来保护客户端和服务器之间的通信，包括createUser发送的密码。For instructions on enabling TLS transport encryption, see Configure mongod and mongos for TLS/SSL on Self-Managed Deployments.有关启用TLS传输加密的说明，请参阅在自我管理部署上为TLS/SSL配置mongod和mongos。

MongoDB does not store the password in cleartext. The password is only vulnerable in transit between the client and the server, and only if TLS transport encryption is not enabled.MongoDB不以明文形式存储密码。密码仅在客户端和服务器之间传输时易受攻击，并且只有在未启用TLS传输加密的情况下才易受攻击。

External Credentials外部凭证

Users created on the $external database should have credentials stored externally to MongoDB, as, for example, with MongoDB Enterprise installations that use Kerberos.在$external数据库上创建的用户应该将凭据存储在MongoDB的外部，例如使用Kerberos的MongoDB Enterprise安装。

To use Client Sessions and Causal Consistency Guarantees with $external authentication users (Kerberos, LDAP, or X.509 users), usernames cannot be greater than 10k bytes.要对$external身份验证用户（Kerberos、LDAP或X.509用户）使用客户端会话和因果一致性保证，用户名不能大于10k字节。

local Database数据库

You cannot create users on the local database.您无法在本地数据库上创建用户。

Username Limits用户名限制

Usernames must consist of at least one character and cannot be larger than 7MB.用户名必须至少包含一个字符，并且不能大于7MB。

Required Access所需访问权限

The userAdmin and userAdminAnyDatabase built-in roles provide createUser and grantRole actions on their respective resources.userAdmin和userAdminAnyDatabase内置角色在各自的资源上提供createUser和grantRole操作。

Example示例

The following createUser command creates a user accountAdmin01 on the products database. 以下createUser命令在products数据库上创建用户accountAdmin01。The command gives accountAdmin01 the clusterAdmin and readAnyDatabase roles on the admin database and the readWrite role on the products database:该命令为accountAdmin01赋予了admin数据库上的clusterAdmin和readAnyDatabase角色，以及products数据库上的readWrite角色：

Tip

You can use the passwordPrompt() method in conjunction with various user authentication management methods and commands to prompt for the password instead of specifying the password directly in the method or command call. 您可以将passwordPrompt()方法与各种用户身份验证管理方法和命令结合使用，以提示输入密码，而不是直接在方法或命令调用中指定密码。However, you can still specify the password directly as you would with earlier versions of the mongo shell.但是，您仍然可以像使用早期版本的mongo shell一样直接指定密码。

 db.getSiblingDB("products").runCommand( {
       createUser: "accountAdmin01",
       pwd: passwordPrompt(),
       customData: { employeeId: 12345 },
       roles: [
                { role: "clusterAdmin", db: "admin" },
                { role: "readAnyDatabase", db: "admin" },
                "readWrite"
              ],
       writeConcern: { w: "majority" , wtimeout: 5000 }
} )