Create a User¶

On this page

Prerequisites
Procedure
Additional Examples
Next Steps

With access control enabled, users are required to identify themselves. You have to grant a user one or more roles. A role grants a user privileges to perform certain actions on MongoDB resources.

Each application and user of a MongoDB system should map to a distinct user. This principle of access isolation facilitates access revocation and ongoing user maintenance. To ensure a system of least privilege, only grant the minimal set of privileges required to a user.

Prerequisites¶

To be able to create users, you need to:

enable access control
create a user administrator

For routine user creation, you must possess the following permissions:

To create a new user in a database, you must have the createUser action on that database resource.
To grant roles to a user, you must have the grantRole action on the role’s database.

The userAdmin and userAdminAnyDatabase built-in roles provide createUser and grantRole actions on their respective resources.

Procedure¶

Note

The following procedure uses SCRAM authentication. For additional information on other authentication mechanisms, see Additional Examples.

1

Connect and authenticate¶

Using mongosh, connect to your primary mongod or, in a sharded cluster, connect to your mongos and authenticate as a user administrator or a user with the required privileges:

Authenticate during Connection
Authenticate after Connection

Start mongosh with the -u <username>, -p, and the --authenticationDatabase <database> command line options:

copy

mongosh --port 27017  --authenticationDatabase \
    "admin" -u "myUserAdmin" -p

Enter your password when prompted.

Using mongosh, connect to your database deployment:

copy

mongosh --port 27017

In mongosh, switch to the authentication database (in this case, admin), and use the db.auth(<username>, <pwd>) method to authenticate:

copy

use admin
db.auth("myUserAdmin", passwordPrompt()) // or cleartext password

Tip

The passwordPrompt() method prompts you to enter the password. You can also specify your password directly as a string. We recommend to use the passwordPrompt() method to avoid the password being visible on your screen and potentially leaking the password to your shell history.

Enter the password when prompted.

2

Create additional users for your deployment¶

Note

The following step uses SCRAM authentication. For additional information on other authentication mechanisms, see Additional Examples.

After authenticating as the user administrator, use the db.createUser() method to create additional users. You can assign any built-in roles or user-defined roles to the users.

The following operation adds a user myTester to the test database who has the readWrite role in the test database as well as the read role in the reporting database.

copy

use test
db.createUser(
  {
    user: "myTester",
    pwd:  passwordPrompt(),   // or cleartext password
    roles: [ { role: "readWrite", db: "test" },
             { role: "read", db: "reporting" } ]
  }
)

Tip

The passwordPrompt() method prompts you to enter the password. You can also specify your password directly as a string. We recommend to use the passwordPrompt() method to avoid the password being visible on your screen and potentially leaking the password to your shell history.

The database where you create the user (in this example, test) is that user’s authentication database. Although the user authenticates to this database, the user can have roles in other databases. The user’s authentication database does not limit the user’s privileges.

After creating the additional users, exit mongosh.

3

Connect to the instance and authenticate as `myTester`¶

Important

It is not possible to switch between users in the same mongosh session. Authenticating as a different user means the session has the privileges of both authenticated users. To switch between users exit and relaunch mongosh.

After exiting mongosh as myUserAdmin, reconnect as myTester:

Authenticate during Connection
Authenticate after Connection

Start mongosh with the -u <username>, -p, and the --authenticationDatabase <database> command line options:

copy

mongosh --port 27017 -u "myTester" \
    --authenticationDatabase "test" -p

Enter the password for the user when prompted.

Using mongosh, connect to your database deployment:

copy

mongosh --port 27017

In mongosh, switch to the authentication database (in this case, admin), and use the db.auth(<username>, <pwd>) method to authenticate:

copy

use test
db.auth("myTester", passwordPrompt())  // or cleartext password

Tip

The passwordPrompt() method prompts you to enter the password. You can also specify your password directly as a string. We recommend to use the passwordPrompt() method to avoid the password being visible on your screen and potentially leaking the password to your shell history.

Enter the password for the user when prompted.

4

Insert a document as `myTester`¶

As the user myTester, you have privileges to perform read and write operations in the test database (as well as perform read operations in the reporting database). Once authenticated as myTester, insert a document into a collection in the test database. For example, you can perform the following insert operation in the test database:

copy

db.foo.insertOne( { x: 1, y: 1 } )

See also

Manage Users and Roles

Additional Examples¶

Username/Password Authentication¶

The following operation creates a user in the reporting database with the specified name, password, and roles.

Tip

The passwordPrompt() method prompts you to enter the password. You can also specify your password directly as a string. We recommend to use the passwordPrompt() method to avoid the password being visible on your screen and potentially leaking the password to your shell history.

copy

use reporting
db.createUser(
  {
    user: "reportsUser",
    pwd: passwordPrompt(),  // or cleartext password
    roles: [
       { role: "read", db: "reporting" },
       { role: "read", db: "products" },
       { role: "read", db: "sales" },
       { role: "readWrite", db: "accounts" }
    ]
  }
)

Kerberos Authentication¶

Users that authenticate to MongoDB using an external authentication mechanism, such as Kerberos, must be created in the $external database, which allows mongos or mongod to consult an external source for authentication.

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.

For Kerberos authentication, you must add the Kerberos principal as the username. You do not need to specify a password.

The following operation adds the Kerberos principal reportingapp@EXAMPLE.NET with read-only access to the records database:

copy

use $external
db.createUser(
    {
      user: "reportingapp@EXAMPLE.NET",
      roles: [
         { role: "read", db: "records" }
      ]
    }
)

See also

For more information about setting up Kerberos authentication for your MongoDB deployment, see the following tutorials:

LDAP Authentication¶

Users that authenticate to MongoDB using an external authentication mechanism, such as LDAP, must be created in the $external database, which allows mongos or mongod to consult an external source for authentication.

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.

For LDAP authentication, you must specify a username. You do not need to specify the password, as that is handled by the LDAP service.

The following operation adds the reporting user with read-only access to the records database:

copy

use $external
db.createUser(
    {
      user: "reporting",
      roles: [
         { role: "read", db: "records" }
      ]
    }
)

See also

For more information about setting up LDAP authentication for your MongoDB deployment, see the following tutorials:

x.509 Client Certificate Authentication¶

Users that authenticate to MongoDB using an external authentication mechanism, such as x.509 Client Certificate Authentication, must be created in the $external database, which allows mongos or mongod to consult an external source for authentication.

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.

For x.509 Client Certificate authentication, you must add the value of the subject from the client certificate as a MongoDB user. Each unique x.509 client certificate corresponds to a single MongoDB user. You do not need to specify a password.

The following operation adds the client certificate subject CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry user with read-only access to the records database.

copy

use $external
db.createUser(
    {
      user: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry",
      roles: [
         { role: "read", db: "records" }
      ]
    }
)

See also

For more information about setting up x.509 Client Certificate authentication for your MongoDB deployment, see the following tutorials:

Use x.509 Certificates to Authenticate Clients

Next Steps¶

To manage users, assign roles, and create custom roles, see Manage Users and Roles.

← Users Authenticate a User →

Create a User¶

Prerequisites¶

Procedure¶

Connect and authenticate¶

Create additional users for your deployment¶

Connect to the instance and authenticate as myTester¶

Insert a document as myTester¶

Additional Examples¶

Username/Password Authentication¶

Kerberos Authentication¶

LDAP Authentication¶

x.509 Client Certificate Authentication¶

Next Steps¶

Connect to the instance and authenticate as `myTester`¶

Insert a document as `myTester`¶