Docs Menu
Docs Home
/
MongoDB Manual
/
Security
/
Authentication
/
Users

Add Users

On this page

  • Overview
  • MongoDB Atlas Limitations
  • Prerequisites
  • Procedure
  • Configure Database Users for MongoDB Atlas
  • Examples
  • Username/Password Authentication
  • Kerberos Authentication
  • LDAP Authentication
  • x.509 Client Certificate Authentication
  • Next Steps

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.

The user information on this page applies to deployments hosted in all of the following environments unless specified otherwise:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Atlas Limitations

The following limitations apply only to deployments hosted in MongoDB Atlas. If any of these limits present a problem for your organization, contact Atlas support.

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:

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

To create users for MongoDB Atlas, you must have Organization Owner or Project Owner access to MongoDB Atlas. These roles are unique to MongoDB Atlas and are separate from database users. To learn more, see Atlas User Roles.

Procedure

Note

The following procedures use SCRAM authentication. For additional information on other authentication mechanisms, see Examples.

Configure Database Users for MongoDB Atlas

A MongoDB Atlas project can have users with different authentication methods.

You cannot change a user's authentication method after creating that user. To use an alternative authentication method, you must create a new user.

Configure database users for your MongoDB Atlas deployment who use SCRAM authentication:

The Atlas CLI uses the following commands to create new database users and X.509 certificates. The options you specify determine the authentication method.

To create a database user for your project using the Atlas CLI, run the following command:

atlas dbusers create [builtInRole]... [options]

To create a new Atlas-managed X.509 certificate for the specified database user using the Atlas CLI, run the following command:

atlas dbusers certs create [options]

To learn more about the syntax and parameters for the previous commands, see the Atlas CLI documentation for atlas dbusers create and atlas dbusers certs create.

Tip

See: Related Links

1

Open the Add New Database User dialog.

  1. In the Security section of the left navigation, click Database Access. The Database Users tab displays.

  2. Click Add New Database User.

2

Select Password.

In the Authentication Method section of the Add New Database User modal window, select the box labeled Password.

3

Enter user information.

Under Password Authentication, there are two text fields.

  1. Enter a username for the new user in the top text field.

  2. Enter a password for the new user in the lower text field.

To use a password auto-generated by MongoDB Atlas, click the Autogenerate Secure Password button.

4

Assign privileges.

Select the database user privileges. You can assign privileges to the new user in one or more of the following ways:

  • Select a built-in role from the Built-in Role dropdown menu. You can select one built-in role per database user within the Atlas UI. If you delete the default option, you can click Add Built-in Role to select a new built-in role.

  • If you have any custom roles defined, you can expand the Custom Roles section and select one or more roles from the Custom Roles dropdown menu. Click Add Custom Role to add more custom roles. You can also click the Custom Roles link to see the custom roles for your project.

  • Expand the Specific Privileges section and select one or more privileges from the Specific Privileges dropdown menu. Click Add Specific Privilege to add more privileges. This assigns the user specific privileges on individual databases and collections.

MongoDB Atlas can apply a built-in role, multiple custom roles, and multiple specific privileges to a single database user.

To remove an applied role or privilege, click Delete next to the role or privilege you wish to delete.

Note

MongoDB Atlas doesn't display the Delete icon next to your Built-in Role, Custom Role, or Specific Privilege selection if you selected only one option. You can delete the selected role or privilege once you apply another role or privilege.

For more information on authorization, see Role-Based Access Control and Built-in Roles.

5

Optional: Specify the resources in the project that the user can access.

By default, users can access all the clusters and federated database instances in the project. You can restrict access to specific clusters and federated database instances by performing both of the following steps:

  1. Toggle Restrict Access to Specific Clusters/Federated Database Instances to ON.

  2. Select the clusters and federated database instances to grant the user access to from the Grant Access To list.

6

Optional: Save as temporary user.

Toggle Temporary User to On and choose a time after which MongoDB Atlas can delete the user from the Temporary User Duration dropdown. You can select one of the following time periods for the user to exist:

  • 6 hours

  • 1 day

  • 1 week

In the Database Users tab, temporary users display the time remaining until MongoDB Atlas will delete the user. Once MongoDB Atlas deletes the user, any client or application that uses the temporary user's credentials loses access to the cluster.

7

Click Add User.

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.

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.

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.

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.

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.

To learn more about setting up LDAP authentication for MongoDB Atlas, see Add Database Users in the MongoDB Atlas documentation.

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.

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

Tip

See also:

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

To learn more about setting up x.509 Client Certificate authentication for MongoDB Atlas, see Add Database Users in the MongoDB Atlas documentation.

Next Steps

To manage users, assign roles, and create custom roles for your self-hosted MongoDB Enterprise or MongoDB Community deployment, see Manage Users and Roles.

You can also manage users, assign roles, and create custom roles for your MongoDB Atlas deployment.

Back

Users

Next

Authentication Mechanisms