Updated on 2024-04-29 GMT+08:00

Creating a User

Precautions

  • All the following operations require permissions. By default, user rwuser has the required permissions. If a user-defined user is used for management, check whether the user has the required permissions.
  • Connect to a DB instance as a user who has the required permission (for example, rwuser).
  • You can use createUser to create required users and configure roles to control user rights. Note that the passwordDigestor parameter must be set to server. Otherwise, the command fails to be executed. This restriction is added to prevent security risks.

Creating a User

db.createUser(user, writeConcern)

  • In the command, user is mandatory and the type is document. It contains the identity authentication and access information of the user to be created.
  • writeConcern is an optional parameter of the document type. It contains the write concern level of the creation operation.
The user document defines users. The format is as follows:
{
  user: "<name>",
  pwd: "<cleartext password>",
  customData: { <any information> },
  roles: [
    { role: "<role>", db: "<database>" } | "<role>",
    ...
  ],
  authenticationRestrictions: [
     {
       clientSource: ["<IP>" | "<CIDR range>", ...],
       serverAddress: ["<IP>" | "<CIDR range>", ...]
     },
     ...
  ]
  mechanisms: [ "<SCRAM-SHA-1|SCRAM-SHA-256>", ... ],
  passwordDigestor: "<server|client>"
}
Table 1 Description of parameter user

Field

Type

Description

user

string

The new username.

pwd

string

User password. If you run db.createUser() on the $external database to create a user who stores credentials outside of MongoDB, the pwd field is not required.

customData

Document

Optional. Any information, which can be used to store any data that the administrator wants to associate with this particular user. For example, this could be the user's full name or employee ID.

roles

Array

The role assigned to the user. You can specify an empty array [] to create a user without a role.

authenticationRestrictions

Array

Optional. The authentication restrictions forcibly imposed by the server on the created user. It is used to specify the IP address or IP address segment that can be accessed by the role.

mechanisms

Array

Optional. The specific SCRAM mechanism or mechanisms for the user credentials. Valid values are SCRAM-SHA-1 and SCRAM-SHA-256.

passwordDigestor

string

Optional. Whether to verify the password on the server or client. The default value is server.

Example

  • Assigning Different Roles to Different Databases During User Creation

    The following describes how to use db.createUser() to create user accountAdmin01 in database products.

    use products
    db.createUser( { user: "accountAdmin01",
                     pwd: "Changeme_123",
                     customData: { employeeId: 12345 },
                     roles: [ { role: "clusterAdmin", db: "admin" },
                              { role: "readAnyDatabase", db: "admin" },
                              "readWrite"] },
                   { w: "majority" , wtimeout: 5000 } )
    The preceding operations assign the following roles to user accountAdmin01:
    • Roles clusterAdmin and readAnyDatabase in the admin database
    • Role readWrite in the products database
  • Assigning Different Roles to a Database During User Creation

    The following describes how to create a user named accountUser whose roles are readWrite and dbAdmin in the products database.

    use products
    db.createUser(
       {
         user: "accountUser",
         pwd: "Changeme_123",
         roles: [ "readWrite", "dbAdmin" ]
       }
    )
  • No Assigning Any Role During User Creation

    The following describes how to create a user named reportsUser with no role assigned in the admin database.

    use admin
    db.createUser(
       {
         user: "reportsUser",
         pwd: "Chagneme_123",
         roles: [ ]
       }
    )
  • Creating an Administrator and Assigning a Role to the Administrator

    The following describes how to create a user named appAdmin in the admin database and grant the user the read and write permissions on the config database so that the user can change some settings of a sharded cluster, such as the shard balancer settings.

    use admin
    db.createUser(
       {
         user: "appAdmin",
         pwd: "Changeme_123",
         roles:
           [
             { role: "readWrite", db: "config" },
             "clusterAdmin"
           ]
       }
    )
  • Creating a User with Authentication Restrictions

    The following describes how to create a user named restricted in the admin database. User authentication is required only when the user connects 192.0.2.0 to 198.51.100.0.

    use admin
    db.createUser(
       {
         user: "restricted",
         pwd: "Changeme_123",
         roles: [ { role: "readWrite", db: "reporting" } ],
         authenticationRestrictions: [ {
            clientSource: ["192.0.2.0"],
            serverAddress: ["198.51.100.0"]
         } ]
       }
    )
  • Creating a User Using Only the SCRAM-SHA-256 Certificate

    The following describes how to create a user with only the SCRAM-SHA-256 certificate.

    use reporting
    db.createUser(
       {
         user: "reportUser256",
         pwd: "Changeme_123",
         roles: [ { role: "readWrite", db: "reporting" } ],
         mechanisms: [ "SCRAM-SHA-256" ]
       }
    )

    If the authenticationMechanisms parameter is set, the mechanisms field can contain only the values specified in the authenticationMechanisms parameter.