system.users Collection

The system.users collection in the admin database stores userauthentication and authorization information. To manage data in this collection,MongoDB provides user management commands.

system.users Schema

The documents in the system.users collection have the followingschema:

  1. {
  2.   _id: <system defined id>,
  3.   userId : <system assigned UUID>,  // Starting in MongoDB 4.0.9
  4.   user: "<name>",
  5.   db: "<database>",
  6.   credentials: { <authentication credentials> },
  7.   roles: [
  8.            { role: "<role name>", db: "<database>" },
  9.            ...
  10.          ],
  11.   customData: <custom information>,
  12.   authenticationRestrictions : [ <documents> ] // Starting in MongoDB 4.0
  13.  }

Each system.users document has the following fields:

  • admin.system.users.userId
  • A unique identifier for the user assigned to the user upon creation.

userId is available for userscreated in MongoDB 4.0.9 and later.

New in version 4.0.9.

  • admin.system.users.user
  • The user name. A user exists in the context of a single logicaldatabase (see admin.system.users.db) but can have access onother databases through roles specified in theroles array.
  • admin.system.users.db
  • The authentication databaseassociated with the user. The user’s privileges are not necessarilylimited to this database. The user can have privileges in additionaldatabases through the roles array.
  • admin.system.users.credentials
  • User’s authentication information. For users with externally storedauthentication credentials, such as users that use Kerberosor x.509 certificates for authentication, the system.usersdocument for that user does not contain thecredentials field. ForSCRAM user credentials, the informationincludes the mechanism, iteration count, and authentication parameters.

See also

A role document has the following syntax:

  1. { role: "<role name>", db: "<database>" }

A role document has the following fields:

  • admin.system.users.roles[n].role

  • The name of a role. A role can be a built-in role provided by MongoDB or a customuser-defined role.

  • admin.system.users.roles[n].db

  • The name of the database where role is defined.

When specifying a role using the role management or user management commands, you can specify the role name alone(e.g. "readWrite") if the role that exists on the database on whichthe command is run.

  • admin.system.users.customData
  • Optional custom information about the user.
  • admin.system.users.authenticationRestrictions
  • An array of authentication restrictions the server enforces for theuser. The array containsa list of IP addresses and CIDR ranges fromwhich the user is allowed to connect to the server or from which theserver can accept users.

New in version 4.0.

Example

Consider the following document in the system.users collection:

  1. {
  2.    "_id" : "home.Kari",
  3.    "userId" : UUID("ec1eced7-055a-4ca8-8737-60dd02c52793"),  // Available starting in MongoDB 4.0.9
  4.    "user" : "Kari",
  5.    "db" : "home",
  6.    "credentials" : {
  7.       "SCRAM-SHA-1" : {
  8.          "iterationCount" : 10000,
  9.          "salt" : "S/xM2yXFosynbCu4GzFDgQ==",
  10.          "storedKey" : "Ist4cgpEd1vTbnRnQLdobgmOsBA=",
  11.          "serverKey" : "e/0DyzS6GPboAA2YNBkGYm87+cg="
  12.       },
  13.       "SCRAM-SHA-256" : {
  14.          "iterationCount" : 15000,
  15.          "salt" : "p1G+fZadAeYAbECN8F/6TMzXGYWBaZ3DtWM0ig==",
  16.          "storedKey" : "LEgLOqZQmkGhd0owm/+6V7VdJUYJcXBhPUvi9z+GBfk=",
  17.          "serverKey" : "JKfnkVv9iXwxyc8JaapKVwLPy6SfnmB8gMb1Pr15T+s="
  18.       }
  19.    },
  20.    "authenticationRestrictions" : [                           // Available starting in MongoDB 4.0
  21.       { "clientSource" : [ "69.89.31.226" ], "serverAddress" : [ "172.16.254.1" ] }
  22.    ],
  23.    "customData" : {
  24.       "zipCode" : "64157"
  25.    },
  26.    "roles" : [
  27.       {
  28.          "role" : "read",
  29.          "db" : "home"
  30.       },
  31.       {
  32.          "role" : "readWrite",
  33.          "db" : "test"
  34.       }
  35.    ]
  36. }

The document shows that a user Kari’s authentication database isthe home database. Kari has the read role in thehome database, the readWrite role in the testdatabase.