Getting Started with MongoDB User Management

One of the first tasks after getting your MongoDB database server up and running is to configure your users and databases. In this post, we’ll go over some of the common scenarios of creating and configuring users in MongoDB. MongoDB user management has improved very significantly over the previous two releases and is now a capable and functional user management model. Users can be assigned various roles, and roles can be configured with desired privileges. There are several built-in user roles to use, or you can create your own custom roles.

The examples in this post use a 2.6.4 client and a 2.6.4 server. Considerable changes were made to the user management model from 2.4 to 2.6.  So, if you’re using a 2.4 client, a lot of the examples in this post will not work for you. You can check the version of yoMongoDBodb client using the following syntax:

mongo --version

Adding a User to a Database

The first step after creating your user is to create your application database:

use applicationdb;

After creating this database, we want to create the user that will be used by the application to write to this database. We want this user to have read and write privileges to the database:

db.createUser({'user':'appuser', 'pwd':'', roles:['readWrite']});

Sometimes, we also want to add users who have read-only access to the database. For example, we might want to add an analytics user who only has read-only access to the database:

db.createUser({'user':'analyticsuser', 'pwd':'', roles:['read']});

Now that the users are created, let’s try to connect as this user from the MongoDB console:

mongo -u 'appuser' -p  <servername>/applicationdb
MongoDB shell version: 2.6.4
connecting to: <servername>/applicationdb

You should have successfully connected! Note the “/applicationdb” at the end of the syntax tells MongoDB to authenticate the ‘appuser’ on the ‘applicationdb’ database.

Adding a User to Multiple Databases

In many scenarios, we need to create multiple databases on the server. For example, in this scenario, we might need to create another database ‘analyticsdb’ to store the results of the analytics. The ‘analyticsuser’ now needs ‘readonly’ access on the ‘applicationdb’ and ‘readWrite’ permissions on the ‘analyticsdb’.

So, how do we achieve this? Should we add the ‘analyticsuser’ to each database? This creates a management nightmare over the long term as many users and databases are added. Fortunately, there is a simple solution. We can centralize the role assignments for a user and store them in a single database. In this scenario, I prefer to store these assignments in the ‘admin’ database since it’s the hub of central administration in the server, but you can also store it in a separate database:

use admin
db.createUser({user:'analyticsuser', pwd:'<pass>', roles:[{'role':'read', 'db':'applicationdb'}, { 'role':'readWrite', 'db':'analyticsdb'}]});

Once it is added, you can use ‘show users’ to show the details of your users. Here is what my admin database looks like:

use admin
> show users
"_id" : "admin.admin",
"user" : "admin",
"db" : "admin",
"roles" : [{ "role" : "root","db" : "admin"},{"role" : "restore","db" : "admin"}]
{"_id" : "admin.analyticsuser",
"user" : "analyticsuser",
"db" : "admin",
"roles" : [{"role" : "read","db" : "applicationdb"},{"role" : "readWrite","db" : 'analyticsdb"}]

Now that our user is added, let’s try to connect from the console to verify the authentication by using the syntax we used above:

mongo -u 'analyticsuser' -p <pass> <servername>/applicationdb

However, authentication fails:

2014-10-06T23:11:42.616+0000 Error: 18 { ok: 0.0, errmsg: "auth failed", code: 18 } at src/mongo/shell/db.js:1210
exception: login failed

The reason is that the ‘analyticsuser’ is defined on the ‘admin’ database and not on the ‘applicationdb’. The way to specify this is to use the ‘–authenticationDatabase’ parameter.

mongo -u 'analyticsuser' -p <pass> <servername>/applicationdb --authenticationDatabase 'admin'

This time, the login succeeds:

MongoDB shell version: 2.6.4
connecting to: <servername>/applicationdb

To better understand the various other built-in roles available in MongoDB, you can refer to the MongoDB documentation on Built-in roles. As always, if you have further questions you can reach us at

Dharshan is the founder of (formerly He is an experienced MongoDB developer and administrator. He can be reached for further comment at @dharshanrg

  • scott anderson

    Hi, how would you use the below command while connecting to a client like robomongo.

    mongo -u ‘username’ -p ‘pass123′ –authenticationDatabase ‘admin’