- Security >
- Security Reference >
system.users
Privilege Documents
system.users
Privilege Documents¶
Changed in version 2.4.
On this page
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:Note
The
pwd
anduserSource
fields are mutually exclusive. A single document cannot contain both.The following privilege document with the
otherDBRoles
field is only supported on theadmin
database: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 theotherDBRoles
field on theadmin
database, theuserSource
field, or the Any Database Roles.
-
<database>.system.users.
pwd
¶ pwd
holds a hashed shared secret used to authenticate theuser
.pwd
field is mutually exclusive with theuserSource
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 amongod
instance’s data.A
userSource
anduser
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:
This user has the following privileges:
clusterAdmin
on theadmin
database,read
on theconfig
database, anddbAdmin
on therecords
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
:
Then for every database that the application0
user requires
access, add documents to the system.users
collection that resemble the following:
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: