How to List All Users in the Mongo Shell

In this MongoDB article, you will learn how to authenticate a user, list all users in the Mongo shell, and use the db.getUser() and db.getUsers() methods. The commands and outputs follow the MongoDB 8.0 documentation and are run in mongosh, the MongoDB Shell.

MongoDB users are defined per database: a user exists in one authentication database, and every command in this article runs against a specific database. Most examples use the admin database, where administrators usually create users.

Authenticate a User

To authenticate as a user, you must provide a username, password, and the authentication database associated with that user. It is not possible to switch between users in the same mongosh session: authenticating as a different user means the session has the privileges of both authenticated users. To switch between users, exit and relaunch mongosh.

Using mongosh, you can either authenticate during connection or authenticate after connection.

Authenticate During Connection

Start mongosh with the -u, -p, and --authenticationDatabase command-line options:

mongosh --port 27017 --authenticationDatabase "admin" -u "myUserAdmin" -p

Enter your password when prompted.

Authenticate After Connection

Connect mongosh to the mongod or mongos instance without credentials:

mongosh --port 27017

In mongosh, switch to the authentication database (in this case, admin), and use the db.auth() method or the authenticate command to authenticate against the authentication database:

use admin
db.auth("myUserAdmin", passwordPrompt()) // or cleartext password

The passwordPrompt() method prompts you to enter the password. You can also specify your password directly as a string, but passwordPrompt() is recommended to avoid the password being visible on your screen and potentially leaking the password to your shell history.

List All Users in the Mongo Shell

The shell helper show users lists all the users of the current database; it runs db.getUsers(), which is described in its own section below. Switch to the database whose users you want to list first — for users created in admin, that is:

use admin
show users

The output contains one document per user, with fields such as _id, userId, user, db, roles, and mechanisms. Because users belong to a database, run the command once per database to inspect the users of another database.

You must not modify the system.users collection directly. To manage the users, use the designated user management commands and methods, such as db.getUser(), db.getUsers(), and db.createUser().

db.getUser() Method in MongoDB

The db.getUser() method returns the user information for a specified user. Run this method on the user’s database; the user must exist on that database, and if the user does not exist, the method returns null. The method has the following syntax:

db.getUser(username, args)

The db.getUser() method consists of the following parameters:

The args document supports the following fields:

db.getUser( "<username>", {
   showCredentials: <Boolean>,
   showCustomData: <Boolean>,
   showPrivileges: <Boolean>,
   showAuthenticationRestrictions: <Boolean>,
   filter: <document>
} )

The db.getUser() method wraps the usersInfo: <username> command. To view another user’s information, you must have the viewUser action on the other user’s database. Users can view their own information.

Example: the following operations return information about an example appClient user in an accounts database:

use accounts
db.getUser("appClient")

The output for the example above is given below:

{
   _id: 'accounts.appClient',
   userId: UUID("1c2fc1bf-c4dc-4a22-8b04-3971349ce0dc"),
   user: 'appClient',
   db: 'accounts',
   roles: [],
   mechanisms: [ 'SCRAM-SHA-1', 'SCRAM-SHA-256' ]
}

db.getUsers() Method in MongoDB

The db.getUsers() method returns the information for all the users in the database. It wraps the usersInfo: 1 command and has the following syntax:

db.getUsers(<options>)

The db.getUsers() method takes the following options:

db.getUsers( {
   showCredentials: <Boolean>,
   showCustomData: <Boolean>,
   filter: <document>
} )

As with db.getUser(), to view another user’s information, you must have the viewUser action on the other user’s database, and users can view their own information.

Example: the db.getUsers() method can accept a filter document to return information for users that match the filter condition. To view all users for the current database who have SCRAM-SHA-256 credentials, run:

db.getUsers({ filter: { mechanisms: "SCRAM-SHA-256" } })

While viewing all users, you can specify the showCredentials option but not the showPrivileges or the showAuthenticationRestrictions option.

With the help of this MongoDB article, you have learned how to authenticate a user, list all users in the Mongo shell, and use the db.getUser() and db.getUsers() methods.