• Security >
• Security Reference >
• system.users Privilege Documents

system.users Privilege Documents

Changed in version 2.4.

Overview

The documents in the <database>.system.users collection store credentials and user privilege information used by the authentication system to provision access to users in the MongoDB system. See User Privilege Roles in MongoDB for more information about access roles, and Security for an overview of security in MongoDB.

Data Model

<database>.system.users

Changed in version 2.4.

Documents in the <database>.system.users collection stores credentials and user roles for users who have access to the database. Consider the following prototypes of user privilege documents:

copy

{
   user: "<username>",
   pwd: "<hash>",
   roles: []
}

copy

{
   user: "<username>",
   userSource: "<database>",
   roles: []
}

Note

The pwd and userSource fields are mutually exclusive. A single document cannot contain both.

The following privilege document with the otherDBRoles field is only supported on the admin database:

copy

{
   user: "<username>",
   userSource: "<database>",
   otherDBRoles: {
      <database0> : [],
      <database1> : []
   },
   roles: []
}

Consider the content of the following fields in the system.users documents:

<database>.system.users.user

user is a string that identifies each user. Users exist in the context of a single logical database; however, users from one database may obtain access in another database by way of the otherDBRoles field on the admin database, the userSource field, or the Any Database Roles.

<database>.system.users.pwd

pwd holds a hashed shared secret used to authenticate the user. pwd field is mutually exclusive with the userSource field.

<database>.system.users.roles

roles holds an array of user roles. The available roles are:

• read
• readWrite
• dbAdmin
• userAdmin
• clusterAdmin
• readAnyDatabase
• readWriteAnyDatabase
• userAdminAnyDatabase
• dbAdminAnyDatabase

See Roles for full documentation of all available user roles.

<database>.system.users.userSource

A string that holds the name of the database that contains the credentials for the user. If userSource is $external, then MongoDB will use an external resource, such as Kerberos, for authentication credentials.

Note

In the current release, the only external authentication source is Kerberos, which is only available in MongoDB Enterprise.

Use userSource to ensure that a single user’s authentication credentials are only stored in a single location in a mongod instance’s data.

A userSource and user pair identifies a unique user in a MongoDB system.

admin.system.users.otherDBRoles

A document that holds one or more fields with a name that is the name of a database in the MongoDB instance with a value that holds a list of roles this user has on other databases. Consider the following example:

copy

{
  user: "admin",
  userSource: "$external",
  roles: [ "clusterAdmin"],
  otherDBRoles:
  {
    config: [ "read" ],
    records: [ "dbAdmin" ]
  }
}

This user has the following privileges:

• clusterAdmin on the admin database,
• read on the config database, and
• dbAdmin on the records database.

Delegated Credentials for MongoDB Authentication

New in version 2.4.

With a new document format in the system.users collection, MongoDB now supports the ability to delegate authentication credentials to other sources and databases. The userSource field in these documents forces MongoDB to use another source for credentials.

Consider the following document in a system.users collection in a database named accounts:

copy

{
   user: "application0",
   pwd: "YvuolxMtaycghk2GMrzmImkG4073jzAw2AliMRul",
   roles: []
}

Then for every database that the application0 user requires access, add documents to the system.users collection that resemble the following:

copy

{
   user: "application0",
   roles: ['readWrite'],
   userSource: "accounts"
}

To gain privileges to databases where the application0 has access, you must first authenticate to the accounts database.

Disable Legacy Privilege Documents

By default MongoDB 2.4 includes support for both new, role-based privilege documents style as well 2.2 and earlier privilege documents. MongoDB assumes any privilege document without a roles field is a 2.2 or earlier document.

To ensure that mongod instances will only provide access to users defined with the new role-based privilege documents, use the following setParameter run-time option:

copy

mongod --setParameter supportCompatibilityFormPrivilegeDocuments=0

←   User Privilege Roles in MongoDB Default MongoDB Port  →

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