createUser

Definition

• createUser
• Creates a new user on the database where you run the command. ThecreateUser command returns a duplicate user error if theuser exists.The createUser command uses the following syntax:

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

{
  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>", ... ],  //Available starting in MongoDB 4.0
  digestPassword: <boolean>
}

createUser has the following fields:

FieldTypeDescriptioncreateUserstringThe name of the new user.pwdstringThe user’s password. The pwd field is notrequired if you run createUser on the $externaldatabase to create users who have credentials stored externally toMongoDB.

The value can be either:

• the user’s password in cleartext string, or
• passwordPrompt() to prompt for the user’s password.

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

customDatadocumentOptional. Any arbitrary information. This field can be used to store any dataan admin wishes to associate with this particular user. For example,this could be the user’s full name or employee id.rolesarrayThe roles granted to the user. Can specify an empty array [] tocreate users without roles.digestPasswordbooleanOptional. Indicates whether the server or the client digests the password.

If true, the server receives undigested password from the client anddigests the password.

If false, the client digests the password and passes the digestedpassword to the server. Not compatible with SCRAM-SHA-256

Changed in version 4.0: The default value is true. In earlier versions, the defaultvalue is false.

writeConcerndocumentOptional. The level of write concern for thecreation operation. The writeConcern document takes the samefields as the getLastError command.authenticationRestrictionsarrayOptional. The authentication restrictions the server enforces on the createduser. Specifies a list of IP addresses andCIDR ranges from which theuser is allowed to connect to the server or from which the server canaccept users.

New in version 3.6.

mechanismsarrayOptional. Specify the specific SCRAM mechanism or mechanisms for creatingSCRAM user credentials. If authenticationMechanisms isspecified, you can only specify a subset of theauthenticationMechanisms.

Valid values are:

• "SCRAM-SHA-1"
  • Uses the SHA-1 hashing function.
• "SCRAM-SHA-256"
  • Uses the SHA-256 hashing function.
  • Requires featureCompatibilityVersion set to 4.0.
  • Requires digestPassword to be true.The default for featureCompatibilityVersion is 4.0 is bothSCRAM-SHA-1 and SCRAM-SHA-256.

The default for featureCompatibilityVersion is 3.6 isSCRAM-SHA-1.

New in version 4.0.

digestPasswordbooleanOptional. Indicates whether the server or the client digests the password.

If true, the server receives undigested password from the client anddigests the password.

If false, the client digests the password and passes the digestedpassword to the server. Not compatible with SCRAM-SHA-256

Changed in version 4.0: The default value is true. In earlier versions, the defaultvalue is false.

Roles

In the roles field, you can specify bothbuilt-in roles and user-definedroles.

To specify a role that exists in the same database wherecreateUser runs, you can either specify the role with the name ofthe role:

"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 rolewith a document.

Authentication Restrictions

New in version 3.6.

The authenticationRestrictions document can contain only thefollowing fields. The server throws an error if theauthenticationRestrictions document contains an unrecognized field:

Important

If a user inherits multiple roles with incompatible authenticationrestrictions, that user becomes unusable.

For example, if a user inherits one role in which theclientSource field is ["198.51.100.0"] and another role inwhich the clientSource field is ["203.0.113.0"] the server isunable to authenticate the user.

For more information on authentication in MongoDB, seeAuthentication.

Behavior

User Id

Starting in version 4.0.9, MongoDB automatically assigns a uniqueuserId to the user upon creation.

Encryption

Warning

By default, createUser sends all specified data to the MongoDBinstance in cleartext, even if using passwordPrompt(). UseTLS transport encryption to protect communications between clientsand the server, including the password sent by createUser. Forinstructions on enabling TLS transport encryption, seeConfigure mongod and mongos for TLS/SSL.

MongoDB does not store the password in cleartext. The passwordis only vulnerable in transit between the client and theserver, and only if TLS transport encryption is not enabled.

External Credentials

Users created on the $external database should have credentialsstored externally to MongoDB, as, for example, with MongoDBEnterprise installations that use Kerberos.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e.Kerberos, LDAP, x.509 users), the usernames cannot be greaterthan 10k bytes.

local Database

You cannot create users on the local database.

Required Access

• To create a new user in a database, you must have thecreateUseraction onthat database resource.
• To grant roles to a user, you must have the grantRoleaction on the role’s database.

The userAdmin anduserAdminAnyDatabase built-in rolesprovide createUser andgrantRole actions on their respective resources.

Example

The following createUser command creates a user accountAdmin01 on theproducts database. The command gives accountAdmin01 theclusterAdmin and readAnyDatabase roles on the admin databaseand the readWrite role on the products database:

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo 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 }
} )