Navigation

usersInfo

On this page

Definition

usersInfo

Returns information about one or more users.

The usersInfo command has the following form:

copy 
{
  usersInfo: <various>,
  showCredentials: <Boolean>,
  showPrivileges: <Boolean>,
  showAuthenticationRestrictions: <Boolean>,
  filter: <document>,
  comment: <any>
}

The command has the following fields:

Field Type Description
usersInfo various

The user(s) about whom to return information.

The argument to usersInfo has multiple forms depending on the requested information. See usersInfo: <various>.
showCredentials boolean Optional. Set the field to true to display the user’s password hash. By default, this field is false.
showPrivileges boolean Optional. Set the field to true to show the user’s full set of privileges, including expanded information for the inherited roles. By default, this field is false. If viewing all users, you cannot specify this field.
showAuthenticationRestrictions boolean Optional. Set the field to true to show the user’s authentication restrictions. By default, this field is false. If viewing all users, you cannot specify this field.
filter document

Optional. A document that specifies $match stage conditions to return information for users that match the filter conditions.

New in version 4.0.
comment any

Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:

A comment can be any valid BSON type (string, integer, object, array, etc).

New in version 4.4.

usersInfo: <various>

copy 
{ usersInfo: <various> }

The argument to usersInfo has multiple forms depending on the requested information:

{ usersInfo: 1 }

Returns information about the users in the database where the command is run.

The mongo shell provides the db.getUsers() helper for this invocation of the command.
{ usersInfo: <username> }

Return information about the a specific user that exists in the database where the command is run.

The mongo shell provides the db.getUser() helper for this invocation of the command.
{ usersInfo: { user: <name>, db: <db> } } Returns information about the user specified by the name and database.
{ usersInfo: [ { user: <name>, db: <db> }, ... ] }
{ usersInfo: [ <username1>, ... ] }
 Returns information about the specified users.
{ forAllDBs: true }

Returns information about users in all databases.

New in version 4.0.

Required Access

Users can always view their own information.

To view another user’s information, the user running the command must have privileges that include the viewUser action on the other user’s database.

Output

The following information can be returned by the usersInfo depending on the options specified:

copy 
{
   "users" : [
      {
         "_id" : "<db>.<username>",
         "userId" : <UUID>,        // Starting in MongoDB 4.0.9
         "user" : "<username>",
         "db" : "<db>",
         "mechanisms" : [ ... ],   // Starting in MongoDB 4.0
         "customData" : <document>,
         "roles" : [ ... ],
         "credentials": { ... }, // only if showCredentials: true
         "inheritedRoles" : [ ... ],  // only if showPrivileges: true or showAuthenticationRestrictions: true
         "inheritedPrivileges" : [ ... ], // only if showPrivileges: true or showAuthenticationRestrictions: true
         "inheritedAuthenticationRestrictions" : [ ] // only if showPrivileges: true or showAuthenticationRestrictions: true
         "authenticationRestrictions" : [ ... ] // only if showAuthenticationRestrictions: true
      },
      ...
   ],
   "ok" : 1
}

Examples

View Specific Users

To see information and privileges, but not the credentials, for the user "Kari" defined in "home" database, run the following command:

copy 
db.runCommand(
   {
     usersInfo:  { user: "Kari", db: "home" },
     showPrivileges: true
   }
)

To view a user that exists in the current database, you can specify the user by name only. For example, if you are in the home database and a user named "Kari" exists in the home database, you can run the following command:

copy 
db.getSiblingDB("home").runCommand(
   {
     usersInfo:  "Kari",
     showPrivileges: true
   }
)

View Multiple Users

To view info for several users, use an array, with or without the optional fields showPrivileges and showCredentials. For example:

copy 
db.runCommand( {
   usersInfo: [ { user: "Kari", db: "home" }, { user: "Li", db: "myApp" } ],
   showPrivileges: true
} )

View All Users for a Database

To view all users on the database the command is run, use a command document that resembles the following:

copy 
db.runCommand( { usersInfo: 1 } )

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

View All Users for a Database that Match the Specified Filter

New in version 4.0: The usersInfo command can accept a filter document to return information for users that match the filter condition.

To view all users in the current database who have the specified role, use a command document that resembles the following:

copy 
db.runCommand( { usersInfo: 1, filter: { roles: { role: "root", db: "admin" } } } )

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

View All Users with SCRAM-SHA-1 Credentials

New in version 4.0: The usersInfo command can accept a filter document to return information for users that match the filter condition.

The following operation returns all users that have SCRAM-SHA-1 credentials. Specifically, the command returns all users across all databases and then uses the $match stage to apply the specified filter to the users.

copy 
db.runCommand( { usersInfo: { forAllDBs: true}, filter: { mechanisms: "SCRAM-SHA-1" } } )

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

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.