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

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

Enable Client 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.

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.

use $external
db.createUser(
    {
      user: "reportingapp@EXAMPLE.NET",
      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.

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.

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.

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.

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 →