Add Users¶

On this page

Overview
Prerequisites
Examples

Overview¶

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

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

Prerequisites¶

If you have enabled access control for your deployment, you can use the localhost exception to create the first user in the system. This first user must have privileges to create other users. As of MongoDB 3.0, with the localhost exception, you can only create users on the admin database. Once you create the first user, you must authenticate as that user to add subsequent users. Enable Access Control provides more detail about adding 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 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.

Examples¶

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

Username/Password Authentication¶

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

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

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

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

Kerberos Authentication¶

Users that will 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.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e. Kerberos, LDAP, x.509 users), the 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: "[email protected]",
      roles: [
         { role: "read", db: "records" }
      ]
    }
)

Configure MongoDB with Kerberos Authentication on Linux and Configure MongoDB with Kerberos Authentication on Windows provide more details about setting up Kerberos authentication for your MongoDB deployment.

LDAP Authentication¶

Users that will 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.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e. Kerberos, LDAP, x.509 users), the 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" }
      ]
    }
)

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

x.509 Client Certificate Authentication¶

Users that will 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.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e. Kerberos, LDAP, x.509 users), the 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" }
      ]
    }
)

Use x.509 Certificates to Authenticate Clients provides details about setting up x.509 Client Certificate authentication for your MongoDB deployment.

← Users Authentication Mechanisms →