> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# usersInfo (database command)

## Definition

Returns information about one or more users.

## Compatibility

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

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

**Important:**

This command is not supported in MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

## Syntax

The command has the following syntax:

```javascript
db.runCommand(
   {
     usersInfo: <various>,
     showCredentials: <Boolean>,
     showCustomData: <Boolean>,
     showPrivileges: <Boolean>,
     showAuthenticationRestrictions: <Boolean>,
     authenticatedMechanism: <string>,
     filter: <document>,
     comment: <any>
   }
)
```

## Command Fields

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: <various>`.](https://www.mongodb.com/docs/manual/reference/command/usersinfo.md#std-label-usersInfo-field-specification) |
| `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 `customData` from 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. |
| `authenticatedMechanism` | string | **New in version 9.0** Optional. Set to a string that represents a supported authentication mechanism to determine where `usersInfo` looks up user authorization information. See [`authenticationMechanisms`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.authenticationMechanisms) for a list of mechanisms and their associated strings. If this field is not specified, `usersInfo` returns information from [LDAP](https://www.mongodb.com/docs/manual/core/security-ldap-external.md#std-label-security-ldap-external) for users defined in the `$external` database, and from the local authorization database for [SCRAM](https://www.mongodb.com/docs/manual/core/security-scram.md#std-label-authentication-scram) users. If viewing all users, you cannot specify this field. |
| `filter` | document | Optional. A document that specifies [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-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](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref), in the `attr.command.cursor.comment` field.; [Database profiler](https://www.mongodb.com/docs/manual/reference/database-profiler.md#std-label-profiler) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/database-profiler.md#mongodb-data-system.profile.command) field.; [`currentOp`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-dbcommand-dbcmd.currentOp) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-data-currentOp.command) field. A comment can be any valid [BSON type](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types) (string, integer, object, array, etc). |

## `usersInfo: <various>`

```javascript
{ 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. [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) provides the [`db.getUsers()`](https://www.mongodb.com/docs/manual/reference/method/db.getusers.md#mongodb-method-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. [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) provides the [`db.getUser()`](https://www.mongodb.com/docs/manual/reference/method/db.getuser.md#mongodb-method-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. |

## 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`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-viewUser) action on the other user's database.

## Output

The following information can be returned by the [`usersInfo`](https://www.mongodb.com/docs/manual/reference/command/usersinfo.md#mongodb-dbcommand-dbcmd.usersInfo) depending on the options specified:

```javascript
{
   "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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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`](https://www.mongodb.com/docs/manual/reference/command/usersinfo.md#mongodb-dbcommand-dbcmd.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:

```javascript
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`](https://www.mongodb.com/docs/manual/reference/command/usersinfo.md#mongodb-dbcommand-dbcmd.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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage to apply the specified filter to the users.

```javascript
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.

### Omit Custom Data from Output

**New in version 5.2**

To omit users' custom data from the [`usersInfo`](https://www.mongodb.com/docs/manual/reference/command/usersinfo.md#mongodb-dbcommand-dbcmd.usersInfo) output, set the `showCustomData` option to `false`.

Use the [`createUser`](https://www.mongodb.com/docs/manual/reference/command/createuser.md#mongodb-dbcommand-dbcmd.createUser) command to create a user named `accountAdmin01` on the `products` database:

```javascript
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, run [`usersInfo`](https://www.mongodb.com/docs/manual/reference/command/usersinfo.md#mongodb-dbcommand-dbcmd.usersInfo) with `showCustomData` set to `false`:

```javascript
db.getSiblingDB("products").runCommand ( {
   usersInfo: "accountAdmin01",
   showCustomData: false
} )
```

Example output:

```javascript
{
   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
}
```