usersInfo (original) (raw)

usersInfo

Returns information about one or more users.

This command is available in deployments hosted in the following environments:

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Note

This command is not supported in MongoDB Atlas. For information on Atlas support for all commands, seeUnsupported Commands.

The command has the following syntax:


db.runCommand(

   {

     usersInfo: <various>,

     showCredentials: <Boolean>,

     showCustomData: <Boolean>,

     showPrivileges: <Boolean>,

     showAuthenticationRestrictions: <Boolean>,

     filter: <document>,

     comment: <any>

   }

)

The command takes 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: .
showCredentials	boolean	Optional. Set to true to display the user's password hash.By default, this field is false.
showCustomData	boolean	Optional. Set to false to omit the user's customDatafrom the output.By default, this field is true.New in version 5.2.
showPrivileges	boolean	Optional. Set 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 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.
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:mongod log messages, in theattr.command.cursor.comment field.Database profiler output, in the command.comment field.currentOp output, in the command.comment field.A comment can be any valid BSON type(string, integer, object, array, etc).

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

Argument	Returns
{ usersInfo: 1 }	Returns information about the users in the database where the command is run.mongosh provides thedb.getUsers() helper for this invocation of the command.
{ usersInfo: }	Return information about the a specific user that exists in the database where the command is run.mongosh provides thedb.getUser() helper for this invocation of the command.
{ usersInfo: { user: , db: } }	Returns information about the user specified by the name and database.
{ usersInfo: [ { user: , db: }, ... ] }{ usersInfo: [ , ... ] }	Returns information about the specified users.
{ forAllDBs: true }	Returns information about users in all databases.

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.

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


{

   "users" : [

      {

         "_id" : "<db>.<username>",

         "userId" : <UUID>,

         "user" : "<username>",

         "db" : "<db>",

         "mechanisms" : [ ... ],

         "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

}

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


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 homedatabase and a user named "Kari" exists in the home database, you can run the following command:


db.getSiblingDB("home").runCommand(

   {

     usersInfo:  "Kari",

     showPrivileges: true

   }

)

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


db.runCommand( {

   usersInfo: [ { user: "Kari", db: "home" }, { user: "Li", db: "myApp" } ],

   showPrivileges: true

} )

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


db.runCommand( { usersInfo: 1 } )

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

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:


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 theshowAuthenticationRestrictions options.

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-1credentials. Specifically, the command returns all users across all databases and then uses the $match stage to apply the specified filter to the users.


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 theshowAuthenticationRestrictions options.

New in version 5.2: To omit users' custom data from the usersInfo output, set the showCustomData option to false.

Use the createUser command to create a user namedaccountAdmin01 on the products database:


db.getSiblingDB("products").runCommand( {

   createUser: "accountAdmin01",

   pwd: passwordPrompt(),

   customData: { employeeId: 12345 },

   roles: [ { role: 'readWrite', db: 'products' } ]

} )

The user contains a customData field of { employeeId: 12345 }.

To retrieve the user but omit the custom data from the output, runusersInfo with showCustomData set to false:


db.getSiblingDB("products").runCommand ( {

   usersInfo: "accountAdmin01",

   showCustomData: false

} )

Example output:


{

   users: [

      {

         _id: 'products.accountAdmin01',

         userId: UUID("0955afc1-303c-4683-a029-8e17dd5501f4"),

         user: 'accountAdmin01',

         db: 'products',

         roles: [ { role: 'readWrite', db: 'products' } ],

         mechanisms: [ 'SCRAM-SHA-1', 'SCRAM-SHA-256' ]

      }

   ],

   ok: 1

}