Skip to content

Commit baa15ae

Browse files
npentreljeff-allen-mongo
npentrel
authored and
jeff-allen-mongo
committed
DOCSP-18009: Refactor Security Users section
1 parent 355d35f commit baa15ae

13 files changed

+352
-253
lines changed

‎source/core/authentication.txt

+3-1
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,8 @@ Getting Started
3030
To get started using access control, follow these tutorials:
3131

3232
- :ref:`enable-access-control`
33-
- :ref:`add-new-user`
33+
- :ref:`create-users`
34+
- :ref:`authentication-auth-as-user`
3435

3536
.. _available-authentication-mechanisms:
3637

@@ -71,3 +72,4 @@ for more information.
7172
/core/authentication-mechanisms
7273
/core/authentication-mechanisms-enterprise
7374
/core/security-internal-authentication
75+
/core/localhost-exception

‎source/core/localhost-exception.txt

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
.. _localhost-exception:
2+
3+
===================
4+
Localhost Exception
5+
===================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
.. important::
16+
17+
On a :binary:`~bin.mongod` instance, the localhost exception only
18+
applies when there are **no users or roles** created in the MongoDB
19+
instance.
20+
21+
The localhost exception allows you to enable access control and then
22+
create the first user or role in the system. After you enable access
23+
control, connect to the localhost interface and create the first user in
24+
the ``admin`` database.
25+
26+
If you create a user first, the user must have privileges to create
27+
other users. The :authrole:`userAdmin` or
28+
:authrole:`userAdminAnyDatabase` role both confer the privilege to
29+
create other users.
30+
31+
.. warning::
32+
33+
Connections using the localhost exception have access to create
34+
*only* the **first user or role**.
35+
36+
Once you create any user or role, the localhost exception is
37+
disabled. If you need to create a user and a role, you must create
38+
the user first using one of the builtin :authrole:`userAdmin` or
39+
:authrole:`userAdminAnyDatabase` roles. If you create a role first,
40+
you won't be able to create a user.
41+
42+
The ability to create a role first with the :method:`db.createRole()`
43+
method is specifically for users authorizing with LDAP. See :ref:`LDAP
44+
Authorization <security-ldap-external>` for more information.
45+
46+
Localhost Exception for Sharded Clusters
47+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
48+
49+
.. important::
50+
51+
- On a :binary:`~bin.mongos`, the localhost exception only applies
52+
when there are no :ref:`sharded cluster users <sharding-localhost>`
53+
or roles created.
54+
- In a sharded cluster, the localhost exception applies to each shard
55+
individually as well as to the cluster as a whole.
56+
57+
Once you create a sharded cluster and add a :ref:`user administrator
58+
<create-user-admin>` through the :binary:`~bin.mongos` instance, you
59+
**must** still prevent unauthorized access to the individual shards. To
60+
prevent unauthorized access to individual shards, follow one of the
61+
following steps for each shard in your cluster:
62+
63+
- :ref:`Create a user administrator <create-user-admin>` on the shard's
64+
primary.
65+
- Disable the localhost exception at startup. To disable the localhost
66+
exception, set the :parameter:`enableLocalhostAuthBypass` parameter to
67+
``0``.

‎source/core/security-users.txt

+76-105
Original file line numberDiff line numberDiff line change
@@ -10,100 +10,100 @@ Users
1010
.. contents:: On this page
1111
:local:
1212
:backlinks: none
13-
:depth: 1
13+
:depth: 2
1414
:class: singlecol
1515

16-
To authenticate a client in MongoDB, you must add a corresponding user to
17-
MongoDB.
16+
To authenticate a client in MongoDB, you must add a corresponding user
17+
to MongoDB.
1818

19+
User Management
20+
---------------
1921

20-
User Management Interface
21-
-------------------------
22+
You can add a user with the :method:`db.createUser()` method using
23+
:binary:`~bin.mongosh`. The first user you create must have privileges
24+
to create other users. The :authrole:`userAdmin` or
25+
:authrole:`userAdminAnyDatabase` role both confer the privilege to
26+
create other users.
2227

23-
To add a user, MongoDB provides the :method:`db.createUser()` method.
24-
When adding a user, you can assign :doc:`roles </core/authorization>` to
25-
the user in order to grant privileges.
26-
27-
.. note::
28+
.. seealso::
2829

29-
The first user created in the database should be a user administrator
30-
who has the privileges to manage other users. See
31-
:doc:`/tutorial/enable-authentication`.
30+
:doc:`/tutorial/create-users`
3231

33-
You can also update existing users, such as to change password and grant
34-
or revoke roles. For a full list of user management methods, see
32+
You can grant a user privileges by assinging :doc:`roles
33+
</core/authorization>` to the user when you create the user. You can
34+
also grant or revoke roles, as well as update passwords, by updating
35+
existing users. For a full list of user management methods, see
3536
:ref:`user-management-methods`.
3637

38+
.. seealso::
39+
40+
:doc:`/tutorial/manage-users-and-roles`
41+
3742
A user is uniquely identified by the user's name and associated
38-
authentication database. Starting in MongoDB 4.0.9, a users managed by
39-
MongoDB are assigned a unique ``userId``. [#userid]_
43+
:ref:`authentication database <authentication-database>`. MongoDB
44+
associates a user with a unique ``userId`` upon creation in MongoDB.
45+
46+
LDAP Managed Users
47+
~~~~~~~~~~~~~~~~~~
48+
49+
:ref:`LDAP managed users <security-ldap>` created on an LDAP
50+
server do not have an associated document in the :doc:`system.users
51+
</reference/system-users-collection>` collection, and therefore don't
52+
have a :data:`~admin.system.users.userId` field associated with them.
4053

41-
.. seealso::
4254

43-
:doc:`/tutorial/create-users`
44-
4555
.. _authentication-database:
4656
.. _user-authentication-database:
4757

4858
Authentication Database
4959
-----------------------
5060

51-
When adding a user, you create the user in a specific database. This
52-
database is the authentication database for the user.
53-
54-
A user can have privileges across different databases; that is, a user's
55-
privileges are not limited to their authentication database. By assigning
56-
to the user roles in other databases, a user created in one database can
57-
have permissions to act on other databases. For more information on
58-
roles, see :doc:`/core/authorization`.
59-
60-
The user's name and authentication database serve as a unique identifier
61-
for that user. [#userid]_ That is, if two users have the same name but are created
62-
in different databases, they are two separate users. If you intend to
63-
have a single user with permissions on multiple databases, create a
64-
single user with roles in the applicable databases instead of creating
65-
the user multiple times in different databases.
61+
When you add a user, you create the user in a specific database. The
62+
database you create the user in is the authentication database for the
63+
user.
6664

67-
.. [#userid]
65+
However, a user's privileges are not limited to their authentication
66+
database. Therefore, a user can have privileges across different
67+
databases. For more information on roles, see
68+
:doc:`/core/authorization`.
6869

69-
Starting in version 4.0.9, MongoDB associates a user with a unique
70-
``userId`` upon creation in MongoDB.
71-
72-
:ref:`LDAP managed users <security-ldap>` created on the LDAP server
73-
do not have an associated document in the :doc:`system.users
74-
</reference/system-users-collection>` collection, and hence, do not
75-
have a :data:`~admin.system.users.userId` field associated with them.
70+
A user's name and authentication database serve as a unique identifier
71+
for that user. MongoDB associates a user with a unique ``userId`` upon
72+
creation in MongoDB. However, :ref:`LDAP managed users <security-ldap>`
73+
created on an LDAP server do not have an associated document in the
74+
:doc:`system.users </reference/system-users-collection>` collection, and
75+
therefore don't have a :data:`~admin.system.users.userId` field
76+
associated with them.
7677

77-
.. _authentication-auth-as-user:
78-
79-
Authenticate a User
80-
-------------------
81-
82-
.. include:: /includes/fact-authenticate.rst
78+
If two users have the same name but are created in different databases,
79+
they are two separate users. If you want to have a single user with
80+
permissions on multiple databases, create a single user with a role for
81+
each applicable database.
8382

8483
Centralized User Data
8584
---------------------
8685

8786
For users created in MongoDB, MongoDB stores all user information,
8887
including :data:`name <admin.system.users.user>`, :data:`password
89-
<admin.system.users.credentials>`, and the :data:`user's authentication
88+
<admin.system.users.credentials>`, and the user's :data:`authentication
9089
database <admin.system.users.db>`, in the :doc:`system.users
9190
</reference/system-users-collection>` collection in the ``admin``
9291
database.
9392

94-
Do not access this collection directly but instead use the :ref:`user
95-
management commands <user-management-commands>`.
96-
93+
Do not modify this collection directly. To manage users, use the
94+
designated :ref:`user management commands <user-management-commands>`.
9795

9896
.. _sharding-localhost:
9997
.. _sharding-security:
10098

10199
Sharded Cluster Users
102100
---------------------
103101

104-
To create users for a sharded cluster, connect to the
105-
:binary:`~bin.mongos` instance and add the users. Clients then
106-
authenticate these users through the :binary:`~bin.mongos` instances.
102+
To create users for a sharded cluster, connect to a
103+
:binary:`~bin.mongos` instance and add the users. To authenticate as a
104+
user created on a :binary:`~bin.mongos` instance, you must authenticate
105+
through a :binary:`~bin.mongos` instance.
106+
107107
In sharded clusters, MongoDB stores user configuration data in the
108108
``admin`` database of the :term:`config servers <config server>`.
109109

@@ -112,62 +112,33 @@ In sharded clusters, MongoDB stores user configuration data in the
112112
Shard Local Users
113113
~~~~~~~~~~~~~~~~~
114114

115-
However, some maintenance operations, such as :dbcommand:`cleanupOrphaned`,
116-
:dbcommand:`compact`, :method:`rs.reconfig()`, require direct connections to
117-
specific shards in a sharded cluster. To perform these operations, you must
118-
connect directly to the shard and authenticate as a *shard local*
119-
administrative user.
120-
121-
To create a *shard local* administrative user, connect directly to the shard
122-
and create the user. MongoDB stores *shard local* users in the ``admin``
123-
database of the shard itself.
124-
125-
These *shard local* users are completely independent from the users added to
126-
the sharded cluster via :binary:`~bin.mongos`. *Shard local* users are local to the
127-
shard and are inaccessible by :binary:`~bin.mongos`.
128-
129-
Direct connections to a shard should only be for shard-specific maintenance and
130-
configuration. In general, clients should connect to the sharded cluster
131-
through the :binary:`~bin.mongos`.
132-
133-
.. _localhost-exception:
134-
135-
Localhost Exception
136-
-------------------
137-
138-
The localhost exception allows you to enable access control and then
139-
create the first user in the system. With the localhost exception, after
140-
you enable access control, connect to the localhost interface and create
141-
the first user in the ``admin`` database. The first user must have
142-
privileges to create other users, such as a user with the
143-
:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role.
144-
Connections using the localhost exception *only* have access to create
145-
the first user on the ``admin`` database.
146-
147-
.. versionchanged:: 3.4
148-
149-
MongoDB 3.4 extended the localhost exception to permit execution of the
150-
:method:`db.createRole()` method. This method allows users authorizing via
151-
LDAP to create a role inside of MongoDB that maps to a role defined
152-
in LDAP. See :ref:`LDAP Authorization <security-ldap-external>` for more
153-
information.
115+
Some maintenance operations, such as :dbcommand:`cleanupOrphaned`,
116+
:dbcommand:`compact`, or :method:`rs.reconfig()`, require direct
117+
connections to specific shards in a sharded cluster. To perform these
118+
operations, you must connect directly to the shard and authenticate as a
119+
*shard local* administrative user.
154120

155-
The localhost exception applies only when there are no users created in the
156-
MongoDB instance.
121+
To create a *shard local* administrative user, connect directly to the
122+
primary of the shard and create the user. For instructions on how to
123+
create a shard local user administrator see the
124+
:doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control`
125+
tutorial.
157126

158-
In the case of a sharded cluster, the localhost exception applies to each shard
159-
individually as well as to the cluster as a whole. Once you create a sharded
160-
cluster and add a user administrator through the :binary:`~bin.mongos` instance,
161-
you must still prevent unauthorized access to the individual shards. Follow one
162-
of the following steps for each shard in your cluster:
127+
MongoDB stores *shard local* users in the ``admin`` database of the
128+
shard itself. These *shard local* users are independent from
129+
the users added to the sharded cluster through a :binary:`~bin.mongos`.
130+
*Shard local* users are local to the shard and are inaccessible by
131+
:binary:`~bin.mongos`.
163132

164-
- Create an administrative user, or
133+
Direct connections to a shard should only be used for shard-specific
134+
maintenance and configuration or for targeted analytics workloads. In
135+
general, clients should connect to the sharded cluster through the
136+
:binary:`~bin.mongos`.
165137

166-
- Disable the localhost exception at startup. To disable the localhost
167-
exception, set the :parameter:`enableLocalhostAuthBypass` parameter to ``0``.
168138

169139
.. toctree::
170140
:titlesonly:
171141
:hidden:
172142

173143
/tutorial/create-users
144+
/tutorial/authenticate-a-user

‎source/includes/access-create-user.rst

+3-4
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
:ref:`action <security-user-actions>` on the role's database.
77

88
The :authrole:`userAdmin` and
9-
:authrole:`userAdminAnyDatabase` built-in roles
10-
provide :authaction:`createUser` and
11-
:authaction:`grantRole` actions on their respective :doc:`resources
12-
</reference/resource-document>`.
9+
:authrole:`userAdminAnyDatabase` built-in roles provide
10+
:authaction:`createUser` and :authaction:`grantRole` actions on their
11+
respective :doc:`resources </reference/resource-document>`.

‎source/includes/extracts-create-users-base.yaml

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
ref: _create-user-intro
22
content: |
3-
Users that will authenticate to MongoDB using an external authentication
4-
mechanism, such as {{mechanism}}, must be created in the ``$external`` database,
5-
which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` to consult an
6-
external source for authentication.
7-
3+
Users that authenticate to MongoDB using an external authentication
4+
mechanism, such as {{mechanism}}, must be created in the ``$external``
5+
database, which allows :binary:`~bin.mongos` or :binary:`~bin.mongod`
6+
to consult an external source for authentication.
7+
88
.. include:: /includes/extracts/sessions-external-username-limit.rst
99
1010
...

‎source/includes/extracts-create-users.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ ref: create-user-intro-kerberos
22
inherit:
33
ref: _create-user-intro
44
file: extracts-create-users-base.yaml
5-
replacement:
5+
replacement:
66
mechanism: "Kerberos"
77
---
88
ref: create-user-intro-ldap
@@ -18,4 +18,4 @@ inherit:
1818
file: extracts-create-users-base.yaml
1919
replacement:
2020
mechanism: "x.509 Client Certificate Authentication"
21-
...
21+
...

‎source/includes/extracts-sessions.yaml

+3-4
Original file line numberDiff line numberDiff line change
@@ -101,11 +101,10 @@ content: |
101101
ref: sessions-external-username-limit
102102
content: |
103103
104-
.. versionchanged:: 3.6.3
104+
To use :ref:`sessions` with ``$external`` authentication users
105+
(Kerberos, LDAP, or x.509 users), the usernames cannot be greater
106+
than 10k bytes.
105107
106-
To use sessions with ``$external`` authentication users (i.e.
107-
Kerberos, LDAP, x.509 users), the usernames cannot be greater
108-
than 10k bytes.
109108
---
110109
ref: sessions-cursor-timeout
111110
content: |

0 commit comments

Comments
 (0)