This version of the documentation is archived and no longer supported.

Add a User to a Database

Changed in version 2.6.


Each application and user of a MongoDB system should map to a distinct application or administrator. This access isolation facilitates access revocation and ongoing user maintenance. At the same time users should have only the minimal set of privileges required to ensure a system of least privilege.

To create a user, you must define the user’s credentials and assign that user roles. Credentials verify the user’s identity to a database, and roles determine the user’s access to database resources and operations.

For an overview of credentials and roles in MongoDB see Security Introduction.


For users that authenticate using external mechanisms, [1] you do not need to provide credentials when creating users.

For all users, select the roles that have the exact required privileges. If the correct roles do not exist, create roles.

You can create a user without assigning roles, choosing instead to assign the roles later. To do so, create the user with an empty roles array.

[1]Configure MongoDB with Kerberos Authentication on Linux, Authenticate Using SASL and LDAP with OpenLDAP, Authenticate Using SASL and LDAP with ActiveDirectory, and x.509 certificates provide external authentication mechanisms.


To create a user on a system that uses authentication, you must authenticate as a user administrator. If you have not yet created a user administrator, do so as described in Create a User Administrator.

Required Access

You must have the createUser action on a database to create a new user on that database.

You must have the grantRole action on a role’s database to grant the role to another user.

If you have the userAdmin or userAdminAnyDatabase role, you have those actions.

First User Restrictions

If your MongoDB deployment has no users, you must connect to mongod using the localhost exception or use the --noauth option when starting mongod to gain full access the system. Once you have access, you can skip to Creating the system user administrator in this procedure.

If users exist in the MongoDB database, but none of them has the appropriate prerequisites to create a new user or you do not have access to them, you must restart mongod with the --noauth option.



Connect to MongoDB with the appropriate privileges.

Connect to the mongod or mongos with the privileges specified in the Prerequisites section.

The following procedure uses the siteUserAdmin created in Create a User Administrator.

mongo --port 27017 -u siteUserAdmin -p password --authenticationDatabase admin

Create the new user.

Create the user in the database to which the user will belong. Pass a well formed user document to the db.createUser() method.

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

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

To authenticate the reportsUser, you must authenticate the user in the reporting database.