Add Users

Overview

MongoDB employs role-based access control (RBAC) to determine accessfor users. A user is granted one or more roles thatdetermine the user’s access or privileges to MongoDB resources and the actionsthat user can perform. A user should have only the minimal set ofprivileges required to ensure a system of least privilege.

Each application and user of a MongoDB system should map to a distinctuser. This access isolation facilitatesaccess revocation and ongoing user maintenance.

Prerequisites

If you have enabled access control for your deployment, you can usethe localhost exception to create the firstuser in the system. This first user must have privileges to createother users. As of MongoDB 3.0, with the localhost exception, youcan only create users on the admin database. Once you create thefirst user, you must authenticate as that user to add subsequent users.Enable Access Control provides more detail aboutadding users when enabling access control for a deployment.

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

• 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.

Examples

To create a user in a MongoDB deployment, you connect to thedeployment, and then use the db.createUser() methodor createUser command to add the user.

Username/Password Authentication

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

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.

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" }
    ]
  }
)

Enable Access Control provides more details aboutenforcing authentication for your MongoDB deployment.

Kerberos Authentication

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

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.

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

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

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

Configure MongoDB with Kerberos Authentication on Linuxand Configure MongoDB with Kerberos Authentication on Windowsprovide more details about setting up Kerberos authentication for yourMongoDB deployment.

LDAP Authentication

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

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.

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

The following operation adds the reporting userwith read-only access to the records database.

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

Authenticate Using SASL and LDAP with ActiveDirectory andAuthenticate Using SASL and LDAP with OpenLDAP provide more detail aboutusing authenticating using LDAP.

x.509 Client Certificate Authentication

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

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.

For x.509 Client Certificate authentication, you must add the value ofthe subject from the client certificate as a MongoDB user. Eachunique 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 subjectCN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountryuser with read-only access to the records database.

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

Use x.509 Certificates to Authenticate Clients provides detailsabout setting up x.509 Client Certificate authentication for yourMongoDB deployment.