usersInfo
Definition
usersInfo
Returns information about one or more users.
The
usersInfo
command has the following form:{ usersInfo: <various>, showCredentials: <Boolean>, showPrivileges: <Boolean>, showAuthenticationRestrictions: <Boolean>, filter: <document>, comment: <any> } The command has the following fields:
FieldTypeDescriptionusersInfo
variousThe user(s) about whom to return information.
The argument to
usersInfo
has multiple forms depending on the requested information. SeeusersInfo: <various>
.showCredentials
booleanOptional. Set the field to true to display the user's password hash. By default, this field isfalse
.showPrivileges
booleanOptional. 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
booleanOptional. 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
documentOptional. A document that specifies$match
stage conditions to return information for users that match the filter conditions.comment
anyOptional. 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 the
attr.command.cursor.comment
field.Database profiler output, in the
command.comment
field.currentOp
output, in thecommand.comment
field.
A comment can be any valid BSON type (string, integer, object, array, etc).
New in version 4.4.
usersInfo: <various>
{ usersInfo: <various> }
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. The |
{ usersInfo: <username> } | Return information about the a specific user that exists in the database where the command is run. The |
{ 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. |
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:
{ "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 }
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:
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:
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:
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:
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
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 the
showAuthenticationRestrictions
options.
View All Users with SCRAM-SHA-1
Credentials
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.
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.