Skip to content

Commit 39a6991

Browse files
JuliaMongoJuliaMongo
authored
(DOCSP-17264) Configuring LDAP for client authentication for the MongoDB resource, Agent, and users (#958)
* First commit * Fixed the TOC, to be continued * Adjusted the TOC again to add the LDAP manage users topic * Adding LDAP settings, to be continued * Fixing build and adding sharded cluster steps * Fixed issues, edited. To be continued * Fixed sharded steps * Fixing build * Edits * Adjusting table column widths * Periodic commit. Added agent LDAP steps. To be continued. * Fix build issues and add ldap agent example * Add user info, rebuilding * Updates to the LDAP user steps * A few additions. Ready for the initial review, maybe * Going over examples * Edits, prep for the initial copy review * Copy review from JW * Add second round copy review, two outstanding qs remain to dev * Added connection string examples, and adjusted ldap settings to be in alphabetical order * Adjusted one table * Fixing the build * One final edit * Adjusting the table * Table widths -- adjusting * Adjusting the table yet again * Last attempt with the table
1 parent 0a55296 commit 39a6991

18 files changed

+867
-48
lines changed

‎source/includes/fact-example-secret-prefix-cluster-file.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. example::
22

3-
If you call your deployment ``my-replica-set`` and you set the
3+
If you call your deployment ``my-deployment`` and you set the
44
prefix to ``mdb``, you must name the |tls| secret for the
5-
client |tls| communications ``mdb-my-replica-set-cert``. Also,
5+
client |tls| communications ``mdb-my-deployment-cert``. Also,
66
you must name the |tls| secret for internal cluster authentication
7-
(if enabled) ``mdb-my-replica-set-clusterfile``.
7+
(if enabled) ``mdb-my-deployment-clusterfile``.

‎source/includes/list-tables/ldap-settings.rst

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
.. list-table::
2+
:widths: 45 10 20 25
3+
:header-rows: 1
4+
5+
* - Key
6+
- Type and necessity
7+
- Description
8+
- Example
9+
10+
* - | ``spec.security``
11+
| :setting:`.authentication.enabled<spec.security.authentication.enabled>`
12+
- | boolean,
13+
| required
14+
- Set to ``true`` to enable LDAP authentication.
15+
- ``true``
16+
17+
* - | ``spec.security``
18+
| :setting:`.authentication.ldap.bindQueryUser<spec.security.authentication.ldap.bindQueryUser>`
19+
- | string,
20+
| required
21+
- Specify the LDAP Distinguished Name to which MongoDB binds when
22+
connecting to the LDAP server.
23+
- ``cn=admin,dc=example,dc=org``
24+
25+
* - | ``spec.security``
26+
| :setting:`.authentication.ldap.bindQueryPasswordSecretRef<spec.security.authentication.ldap.bindQueryPasswordSecretRef.name>`
27+
- | string,
28+
| required
29+
- Specify the name of the |k8s-secret| that contains the
30+
LDAP Bind Distinguished Name's password with which MongoDB binds
31+
when connecting to an LDAP server.
32+
- ``<secret-name>``
33+
34+
* - | ``spec.security``
35+
| :setting:`.authentication.ldap.caConfigMapRef.name<spec.security.authentication.ldap.caConfigMapRef.name>`
36+
- | string,
37+
| optional
38+
- Add the |k8s-configmap|\'s name that stores the custom |certauth|
39+
that you used to sign your deployment's |tls| certificates.
40+
- ``<configmap-name>``
41+
42+
* - | ``spec.security``
43+
| :setting:`.authentication.ldap.caConfigMapRef.key<spec.security.authentication.ldap.caConfigMapRef.key>`
44+
- | string,
45+
| optional
46+
- Add the field name that stores the |certauth| which validates the
47+
LDAP server's |tls| certificate.
48+
- ``<configmap-key>``
49+
50+
* - | ``spec.security``
51+
| :setting:`.authentication.ldap.servers<spec.security.authentication.ldap.servers>`
52+
- | array of strings,
53+
| required
54+
- Specify the list of ``hostname:port`` combinations of one or more
55+
LDAP servers. For each server, use a separate line.
56+
- ``<example.com:636>``
57+
58+
* - | ``spec.security``
59+
| :setting:`.authentication.ldap.transportSecurity<spec.security.authentication.ldap.transportSecurity>`
60+
- | string,
61+
| optional
62+
- Set to ``tls`` to use LDAPS (LDAP over |tls|). Leave blank if your
63+
LDAP server doesn't accept TLS.
64+
- ``tls``
65+
66+
* - | ``spec.security``
67+
| :setting:`.authentication.ldap.userToDNMapping<spec.security.authentication.ldap.userToDNMapping>`
68+
- | string,
69+
| required
70+
- Specify the mapping that maps the username provided to
71+
:binary:`~bin.mongod` or :binary:`~bin.mongos` for authentication
72+
to an LDAP Distinguished Name (DN).
73+
74+
To learn more, see :manual:`security.ldap.userToDNMapping
75+
</reference/configuration-options/#security.ldap.userToDNMapping>`
76+
and :manual:`LDAP Query Templates
77+
</core/security-ldap-external/#ldap-query-template>` in the
78+
MongoDB Server documentation.
79+
- ``<match: "(.+)",substitution: "uid={0},ou=groups,dc=example,dc=org">``
80+
81+
* - | ``spec.security``
82+
| :setting:`.authentication.modes<spec.security.authentication.modes>`
83+
- | string,
84+
| required
85+
- Set to ``LDAP`` to enable authentication through LDAP.
86+
- ``LDAP``
87+
88+
* - | ``spec.security``
89+
| :setting:`.certsSecretPrefix<spec.security.certsSecretPrefix>`
90+
- | string,
91+
| optional
92+
- Add the ``<prefix>`` of the secret name that contains your
93+
MongoDB deployment's |tls| certificates.
94+
95+
.. include:: /includes/fact-example-secret-prefix-cluster-file.rst
96+
- ``devDb``
97+
98+
* - | ``spec.security``
99+
| :setting:`.tls.ca<spec.security.tls.ca>`
100+
- | string,
101+
| optional
102+
- Add the |k8s-configmap|\'s name that stores the custom |certauth|
103+
that you used to sign your deployment's |tls| certificates.
104+
- ``<custom-ca>``

‎source/includes/options-k8s-shared.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1001,7 +1001,7 @@ type: string
10011001
directive: setting
10021002
description: |
10031003
1004-
Name of the user the that {+mdbagent+}s use to interact with your
1004+
Name of the user that the {+mdbagent+}s use to interact with your
10051005
MongoDB deployment. The username is mapped to an LDAP Distinguished
10061006
Name (DN) according to
10071007
:setting:`spec.security.authentication.ldap.userToDNMapping`. The

‎source/includes/steps-add-database-user-ldap.yaml

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
ref: configure-kubectl-user
3+
stepnum: 1
4+
inherit:
5+
file: steps-configure-kubectl-namespace.yaml
6+
ref: configure-kubectl-namespace
7+
---
8+
title: "Copy the following example |k8s-crd|."
9+
level: 4
10+
stepnum: 2
11+
ref: copy-k8s-user-crd
12+
content: |
13+
14+
.. literalinclude:: /reference/k8s/example-ldap-user.yaml
15+
:language: yaml
16+
17+
---
18+
title: "Open your preferred text editor and paste the example |k8s-crd| into a new text file."
19+
stepnum: 3
20+
level: 4
21+
ref: paste-k8s-crd
22+
---
23+
title: "Change the lines for the following parameters, as needed."
24+
level: 4
25+
stepnum: 4
26+
ref: change-k8s-user-crd
27+
content: |
28+
29+
Use the following table to guide you through changing the relevant
30+
lines in the|k8s-crd|. For a full list of LDAP user settings, see
31+
:ref:`security settings <security-settings>` in the |k8s-op-short|
32+
MongoDB resource specification.
33+
34+
.. list-table::
35+
:widths: 20 10 50 20
36+
:header-rows: 1
37+
38+
* - Key
39+
- Type
40+
- Description
41+
- Example
42+
43+
* - ``metadata.name``
44+
- string
45+
- The name of the resource for the MongoDB database user.
46+
47+
.. include:: /includes/fact-resource-name-char-limit.rst
48+
49+
- ``ldap-user-1``
50+
51+
* - ``spec.db``
52+
- string
53+
- The name of the MongoDB database where users will be added. This
54+
value must be ``$external``.
55+
- ``$external``
56+
57+
* - ``spec.mongodbResourceRef.name``
58+
- string
59+
- The name of the :ref:`MongoDB resource <k8s-deploy-mdb-resources>`
60+
to which this user is associated.
61+
- ``my-resource``
62+
63+
* - ``spec.opsManager.configMapRef.name``
64+
- string
65+
- The name of the project containing the MongoDB database
66+
where the user will be added. The
67+
:setting:`spec.cloudManager.configMapRef.name` setting is an
68+
alias for this setting and can be used in its place.
69+
- ``my-project``
70+
71+
* - ``spec.roles.db``
72+
- string
73+
- The database the :ref:`role <roles>` can act on.
74+
- ``admin``
75+
76+
* - ``spec.roles.name``
77+
- string
78+
- The name of the :ref:`role <roles>` to grant the database user.
79+
The role name can be any :ref:`built-in MongoDB role <built-in-roles>`
80+
or :opsmgr:`custom role </tutorial/manage-mongodb-roles>` that
81+
exists in |com|.
82+
- ``readWriteAnyDatabase``
83+
84+
* - ``spec.username``
85+
- string
86+
- The authenticated username that is mapped to an LDAP Distinguished
87+
Name (DN) according to
88+
:setting:`spec.security.authentication.ldap.userToDNMapping`.
89+
The DN must already exist in your LDAP deployment.
90+
This username must comply with the `RFC 2253 <https://tools.ietf.org/html/rfc2253>`__
91+
LDAPv3 Distinguished Name standard. :setting:`transformed <security.ldap.userToDNMapping>`
92+
93+
To learn more, see
94+
:manual:`LDAP Query Templates
95+
</core/security-ldap-external/#ldap-query-template>` in the
96+
MongoDB Manual.
97+
- ``uid=mdb0,dc=example,dc=org``
98+
99+
100+
---
101+
title: "Add any additional roles for the user to the |k8s-crd|."
102+
level: 4
103+
stepnum: 5
104+
ref: add-additional-roles-k8s-user
105+
content: |
106+
You may grant additional roles to this user using the format defined
107+
in the following example:
108+
109+
.. code-block:: yaml
110+
:copyable: false
111+
112+
---
113+
apiVersion: mongodb.com/v1
114+
kind: MongoDBUser
115+
metadata:
116+
name: ldap-user-1
117+
spec:
118+
username: "uid=mdb0,dc=example,dc=org"
119+
db: "$external"
120+
mongodbResourceRef:
121+
name: ldap-replica-set
122+
roles:
123+
- db: "admin"
124+
name: "clusterAdmin"
125+
- db: "admin"
126+
name: "readWriteAnyDatabase"
127+
- db: "admin"
128+
name: "dbAdminAnyDatabase"
129+
130+
...
131+
132+
---
133+
title: "Create the user."
134+
level: 4
135+
stepnum: 6
136+
ref: create-k8s-user
137+
content: |
138+
139+
Invoke the following |k8s| command to create your database user:
140+
141+
.. code-block:: sh
142+
143+
kubectl apply -f <database-user-conf>.yaml
144+
145+
The following examples illustrate the connection string formats that you
146+
can use when enabling authentication with LDAP in |k8s-op-short| MongoDB
147+
deployments. These examples use the ``mongodb`` namespace and a replica
148+
set deployment named ``replica-set-ldap``. The examples are similar for
149+
sharded clusters.
150+
151+
- ``connectionString.standard``::manual:`Standard connection string
152+
</reference/connection-string#std-label-connections-standard-connection-string-format>`
153+
that can connect you to the database as this database user.
154+
155+
.. code-block:: sh
156+
157+
mongodb://replica-set-ldap-0-0-svc.mongodb.svc.cluster.local/?connectTimeoutMS=20000&replicaSet=replica-set-ldap&serverSelectionTimeoutMS=20000&ssl=true&authSource=$external
158+
159+
- ``connectionString.standardSrv``: :manual:`DNS seed list connection string
160+
</reference/connection-string/#dns-seed-list-connection-format>` that
161+
can connect you to the database as this database user.
162+
163+
.. code-block:: sh
164+
165+
mongodb+srv://replica-set-ldap-svc.mongodb.svc.cluster.local/?connectTimeoutMS=20000&replicaSet=replica-set-ldap&serverSelectionTimeoutMS=20000&ssl=true&authSource=$external
166+
167+
Using the previously-shown formats, you can connect to the MongoDB
168+
database with the MongoDB Shell (``mongosh``), as in the following
169+
example:
170+
171+
.. code-block:: sh
172+
173+
mongosh <connection-string> \
174+
--host <my-replica-set>/web1.example.com \
175+
--port 30907 \
176+
--authenticationMechanism PLAIN \
177+
--username cn=rob,cn=Users,dc=ldaps-01,dc=myteam,dc=com
178+
179+
You can use these credentials to
180+
:ref:`connect to a MongoDB Database Resource from Inside Kubernetes <connect-from-inside-k8s>`.
181+
182+
---
183+
title: "View the newly created user in |com|."
184+
level: 4
185+
stepnum: 7
186+
ref: view-k8s-user
187+
content: |
188+
189+
You can view the newly-created user in |com|:
190+
191+
1. From the Project's :guilabel:`Deployment` view, click
192+
the :guilabel:`Security` tab.
193+
194+
#. Click the :guilabel:`MongoDB Users` nested tab.
195+
196+
...

‎source/includes/steps-add-database-user-secret-scram.yaml

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,12 @@ content: |
1616
.. literalinclude:: /reference/k8s/example-scram-user-secret.yaml
1717
:language: yaml
1818
:linenos:
19-
:lines: 1-10,14
20-
:emphasize-lines: 5, 9
2119
2220
or you can choose to use a Base64-encoded password:
2321
2422
.. literalinclude:: /reference/k8s/example-scram-user-secret.yaml
2523
:language: yaml
2624
:linenos:
27-
:lines: 1-7,11-14
28-
:emphasize-lines: 5, 9
2925
3026
.. note::
3127

‎source/includes/steps-add-database-user.yaml

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,30 +5,29 @@ inherit:
55
file: steps-configure-kubectl-namespace.yaml
66
ref: configure-kubectl-namespace
77
---
8-
title: "Copy the following example |k8s-configmap|."
8+
title: "Copy the following example |k8s-crd|."
99
level: 4
1010
stepnum: 2
11-
ref: copy-k8s-user-configmap
11+
ref: copy-k8s-user-crd
1212
content: |
1313
1414
.. literalinclude:: /reference/k8s/example-x509-user.yaml
1515
:language: yaml
16-
:emphasize-lines: 5,7-8,11-13
1716
1817
---
19-
title: "Open your preferred text editor and paste the example ConfigMap into a new text file."
18+
title: "Open your preferred text editor and paste the example |k8s-crd| into a new text file."
2019
stepnum: 3
2120
level: 4
22-
ref: paste-k8s-configmap
21+
ref: paste-k8s-crd
2322
---
24-
title: "Change the five highlighted lines."
23+
title: "Change the lines for the following parameters, as needed."
2524
level: 4
2625
stepnum: 4
27-
ref: change-k8s-user-configmap
26+
ref: change-k8s-user-crd
2827
content: |
2928
30-
Use the following table to guide you through changing the highlighted
31-
lines in the ConfigMap:
29+
Use the following table to guide you through changing the relevant
30+
lines in the |k8s-crd|:
3231
3332
.. list-table::
3433
:widths: 20 20 40 20
@@ -97,7 +96,7 @@ content: |
9796
in |com|.
9897
- ``readWriteAnyDatabase``
9998
---
100-
title: "Add any additional roles for the user to the ConfigMap."
99+
title: "Add any additional roles for the user to the |k8s-crd|."
101100
level: 4
102101
stepnum: 5
103102
ref: add-additional-roles-k8s-user
@@ -107,7 +106,6 @@ content: |
107106
108107
.. code-block:: yaml
109108
:copyable: false
110-
:emphasize-lines: 10-14
111109
112110
---
113111
apiVersion: mongodb.com/v1

0 commit comments

Comments
 (0)