Skip to content

Commit f7c2356

Browse files
kennethdyervarunravi98
kennethdyer
and
varunravi98
authored
DOCSP-28315 X.509 Parameters (#2943)
* DOCSP-28315 Documents X.509 parameters and configuration optiosn for TLS cluster authentication * Fixes build issue * Documents the parameter * Refactors existing rotate page * Override step for procedure * Completes procedure * text adjustment * text adjustments * text adjustments * text adjustments * text adjustments * text adjustments * text adjustments * Clarification per Varun * Splits rotate and rolling upgrades, per feedback from Varun * Adds note on rolling upgrade page * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff * Fixes per Jeff * Update source/includes/extracts-x509-certificate.yaml Co-authored-by: Varun Ravichandran <[email protected]> * Update source/includes/extracts-x509-certificate.yaml Co-authored-by: Varun Ravichandran <[email protected]> * Update source/reference/configuration-options.txt Co-authored-by: Varun Ravichandran <[email protected]> * Fixes per Varun * Fixes per Varun * Fixes per Varun * Fixes per Varun * Fixes per Varun * Fixes per Varun * Fixes per Varun * Fixes per Varun * Fixes spelling * Fixes build issue * Fixes build issue --------- Co-authored-by: Varun Ravichandran <[email protected]>
1 parent eb4739e commit f7c2356

9 files changed

+356
-2
lines changed

‎source/core/security-internal-authentication.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,3 +170,4 @@ see :doc:`/tutorial/upgrade-keyfile-to-x509`.
170170
/tutorial/configure-x509-member-authentication
171171
/tutorial/upgrade-keyfile-to-x509
172172
/tutorial/rotate-x509-membership-certificates
173+
/tutorial/rotate-x509-member-cert

‎source/includes/extracts-x509-certificate.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,12 @@ content: |
101101
CN=host1,OU=Dept1,OU=Sales,O=MongoDB
102102
CN=host2,OU=Dept1,O=MongoDB
103103
104+
You can also specify a custom set of DN attributes and values in the configuration file using the
105+
:setting:`net.tls.clusterAuthX509.attributes` setting. This is useful
106+
when you wish to configure X.509 authentication with member certificates that do not have DC, O, or OU attributes in their subject DNs.
107+
108+
For more information, see :ref:`x509-rotate-member-certs`.
109+
104110
- Either the Common Name (``CN``) or one of the Subject Alternative
105111
Name (``SAN``) entries must match the server hostname for other cluster
106112
members. Starting in MongoDB 4.2, when comparing ``SAN``\s, MongoDB can

‎source/includes/fact-x509-authorization.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
When the server authenticates connections from members, it analyzes the
3+
X.509 certificate to determine whether it belongs to a cluster member.
4+
If the server uses the :setting:`~net.tls.clusterAuthX509.attributes`
5+
setting or the ``attributes`` field on the
6+
:parameter:`tlsClusterAuthX509Override` parameter, it checks
7+
the Distinguished Name (DN) values of the certificate.
8+
If the :setting:`~net.tls.clusterAuthX509.extensionValue` setting or the
9+
``extensionValue`` field of
10+
the :parameter:`tlsClusterAuthX509Override` parameter is set, it checks
11+
the extension values of the certificate. If it finds a match,
12+
it authorizes the connection as a peer.
13+

‎source/includes/procedure-replica-set-restart-primary.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
Restart the primary member:
3+
4+
#. Connect to the primary using :program:`mongosh`, then use the
5+
:method:`rs.stepDown` method to step the member down as the
6+
primary:
7+
8+
.. code-block:: javascript
9+
10+
rs.stepDown()
11+
12+
The cluster promotes a secondary with the new certificate to serve
13+
as the new primary.
14+
15+
#. Use the :method:`db.shutdownServer` method to shut the server down:
16+
17+
.. code-block:: javascript
18+
19+
use admin
20+
db.shutdownServer()
21+
22+
#. Restart the server.
23+

‎source/includes/procedure-replica-set-restart-secondaries.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
2+
Restart each secondary cluster member:
3+
4+
#. Use :program:`mongosh` to connect to each secondary cluster member,
5+
then use the :method:`db.shutdownServer` method to stop the server:
6+
7+
.. code-block:: javascript
8+
9+
use admin
10+
db.shutdownServer()
11+
12+
#. Restart the server.
13+
14+
#. Use the :method:`rs.status` method to determine the member state:
15+
16+
.. code-block:: javascript
17+
18+
rs.status().members
19+
20+
#. Wait for the ``stateStr`` field for this member to show a value of
21+
:replstate:`SECONDARY`, then restart the next secondary.
22+

‎source/reference/configuration-options.txt

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1063,6 +1063,9 @@ Core Options
10631063
clusterPassword: <string>
10641064
CAFile: <string>
10651065
clusterCAFile: <string>
1066+
clusterAuthX509:
1067+
attributes: <string>
1068+
extensionValue: <string>
10661069
CRLFile: <string>
10671070
allowConnectionsWithoutCertificates: <boolean>
10681071
allowInvalidCertificates: <boolean>
@@ -1341,6 +1344,9 @@ Core Options
13411344
clusterCertificateSelector: <string>
13421345
clusterFile: <string>
13431346
clusterPassword: <string>
1347+
clusterAuthX509:
1348+
attributes: <string>
1349+
extensionValue: <string>
13441350
CAFile: <string>
13451351
clusterCAFile: <string>
13461352
CRLFile: <string>
@@ -1614,6 +1620,50 @@ Core Options
16141620

16151621
.. include:: /includes/extracts/tls-facts-see-more.rst
16161622

1623+
1624+
.. setting:: net.tls.clusterAuthX509
1625+
1626+
.. versionadded:: 7.0
1627+
1628+
.. code-block:: yaml
1629+
1630+
net:
1631+
tls:
1632+
clusterAuthX509:
1633+
attributes: <string>
1634+
extensionValue: <string>
1635+
1636+
1637+
.. setting:: net.tls.clusterAuthX509.attributes
1638+
1639+
*Type*: string
1640+
1641+
.. versionadded:: 7.0
1642+
1643+
Specifies a set of X.509 Distinguished Name (DN) attributes and values that
1644+
the server expects cluster member nodes to contain in their certificate
1645+
subject names. This lets you use certificates that don't contain DC,
1646+
O, and OU values to authenticate cluster members.
1647+
1648+
When ``attributes`` is set, MongoDB matches certificates using the DN
1649+
and ignores extension values.
1650+
1651+
1652+
.. setting:: net.tls.clusterAuthX509.extensionValue
1653+
1654+
*Type*: string
1655+
1656+
.. versionadded:: 7.0
1657+
1658+
Specifies an extension value that corresponds to the MongoDB cluster
1659+
membership extension :abbr:`OID`, 1.3.6.1.4.1.34601.2.1.2, that the server expects cluster
1660+
member nodes to contain in their certificates. This allows you
1661+
to use certificates that don't contain DC, O, and OU values to authenticate
1662+
cluster members.
1663+
1664+
When ``extensionValue`` is set, MongoDB matches certificates using
1665+
certificate extension values and ignores the Distinguished Name (DN).
1666+
16171667
.. setting:: net.tls.CAFile
16181668

16191669
*Type*: string

‎source/reference/parameters.txt

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -759,6 +759,24 @@ Authentication Parameters
759759

760760
:parameter:`sslMode`
761761

762+
.. parameter:: tlsClusterAuthX509Override
763+
764+
.. versionadded:: 7.0
765+
766+
Overrides the :setting:`~net.tls.clusterAuthX509` configuration options.
767+
768+
.. code-block:: yaml
769+
770+
setParameter:
771+
tlsClusterAuthX509Override: { attributes: O=MongoDB, OU=MongoDB Server }
772+
773+
The parameter supports ``attributes`` and ``extensionValue`` overrides.
774+
775+
.. include:: /includes/fact-x509-authorization
776+
777+
Use this parameter to rotate certificates when the new certificates have
778+
different attributes or extension values.
779+
762780
.. parameter:: tlsOCSPStaplingTimeoutSecs
763781

764782
.. versionadded:: 4.4

‎source/tutorial/rotate-x509-member-cert.txt

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
.. _x509-rotate-member-certs:
2+
3+
=================================
4+
Rotate X.509 Cluster Certificates
5+
=================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. versionadded:: 7.0
16+
17+
Cluster members can use X.509 certificates for :ref:`membership
18+
authentication <internal-auth-x509>` to identify other servers
19+
in the same deployment.
20+
21+
To identify each other as members, Distinguished Name (DN) values
22+
for the X.509 certificate of each member must have the same
23+
Organization (O), Organizational Unit (OU), and Domain Component (DC)
24+
attributes. Alternatively, the certificates must have the same
25+
extension value.
26+
27+
Clusters adopting new certificates can use the
28+
:parameter:`tlsClusterAuthX509Override` parameter to accept X.509 certificates
29+
with different DN attributes during the certificate rotation procedure. Once
30+
all members use certificates with the new value, remove the override to begin
31+
rejecting the now out of date certificates.
32+
33+
.. note::
34+
35+
To perform a rolling update to rotate certificates on a cluster that doesn't
36+
use the :setting:`net.tls.clusterAuthX509` settings and won't after the update,
37+
see :ref:`x509-rolling-update`.
38+
39+
About This Task
40+
---------------
41+
42+
Consider a replica set where member certificates
43+
(set using the :setting:`~net.tls.clusterFile` and
44+
:setting:`~net.tls.certificateKeyFile` settings)
45+
have Distinguished Name (DN) values that use the ``10gen`` organization
46+
and ``10gen Server`` organizational unit (set using the
47+
:setting:`~net.tls.clusterAuthX509.attributes` setting).
48+
49+
.. code-block:: yaml
50+
:emphasize-lines: 6, 8, 11
51+
52+
security:
53+
clusterAuthMode: x509
54+
net:
55+
tls:
56+
mode: requireTLS
57+
certificateKeyFile: /etc/mycerts/10gen-server1.pem
58+
CAFile: /etc/mycerts/ca.pem
59+
clusterFile: /etc/mycerts/10gen-cluster1.pem
60+
clusterCAFile: /etc/mycerts/ca.pem
61+
clusterAuthX509:
62+
attributes: O=10gen, OU=10gen Server
63+
64+
This tutorial assumes that the new X.509 certificates meet
65+
membership certificate and all other requirements and that
66+
the cluster configuration identifies peer certificates
67+
using Distinguished Name (DN) values.
68+
For details, see :ref:`x509-member-certificate-requirements`.
69+
70+
Steps
71+
-----
72+
73+
These steps update member certificates to use new X.509 certificates on a cluster
74+
configured with the :setting:`~net.tls.clusterAuthX509.attributes` setting.
75+
76+
The new certificates have Distinguished Names (DN) that change the
77+
Organization (O) attributes from ``10gen`` to ``MongoDB`` and the
78+
Organizational Unit (OU) attribute from ``10gen Server`` to ``MongoDB Server``.
79+
80+
.. procedure::
81+
82+
.. step:: Update the TLS Cluster Membership Configuration
83+
84+
Update the configuration file of each server:
85+
86+
* Change :setting:`~net.tls.clusterAuthX509.attributes` setting to use
87+
the values on the new certificate
88+
89+
* Set the :parameter:`tlsClusterAuthX509Override` parameter to use the
90+
DN attributes of the old certificate.
91+
92+
For example:
93+
94+
.. code-block:: yaml
95+
:emphasize-lines: 9, 13
96+
97+
net:
98+
tls:
99+
mode: requireTLS
100+
certificateKeyFile: /etc/mycerts/mongodb-server1.pem
101+
CAFile: /etc/mycerts/ca.pem
102+
clusterFile: /etc/mycerts/mongodb-cluster1.pem
103+
clusterCAFile: /etc/mycerts/ca.pem
104+
clusterAuthX509:
105+
attributes: O=MongoDB, OU=MongoDB Server
106+
security:
107+
clusterAuthMode: x509
108+
setParameter:
109+
tlsClusterAuthX509Override: { attributes: O=10gen, OU=10gen Server }
110+
111+
.. step:: Restart Secondary Cluster Members
112+
113+
.. include:: /includes/procedure-replica-set-restart-secondaries
114+
115+
Secondary servers in the replica set now accept peer connections from
116+
members using certificates with the new DN attributes.
117+
118+
.. step:: Restart Primary Cluster Member
119+
120+
.. include:: /includes/procedure-replica-set-restart-primary
121+
122+
The primary server in the replica set steps down and restarts as a
123+
secondary that now accepts peer connections from members using
124+
certificates with the new DN attributes.
125+
126+
.. step:: Update the TLS Certificates
127+
128+
Update the configuration file of each server:
129+
130+
* Change the :setting:`net.tls.certificateKeyFile` setting to use the
131+
new certificate.
132+
133+
* Change the :setting:`net.tls.clusterFile` setting to use the
134+
new certificate.
135+
136+
For example:
137+
138+
.. code-block:: yaml
139+
:emphasize-lines: 4, 6
140+
141+
net:
142+
tls:
143+
mode: requireTLS
144+
certificateKeyFile: /etc/mycerts/mongodb-server2.pem
145+
CAFile: /etc/mycerts/ca.pem
146+
clusterFile: /etc/mycerts/mongodb-cluster2.pem
147+
clusterCAFile: /etc/mycerts/ca.pem
148+
clusterAuthX509:
149+
attributes: O=MongoDB, OU=MongoDB Server
150+
security:
151+
clusterAuthMode: x509
152+
setParameter:
153+
tlsClusterAuthX509Override: { attributes: O=10gen, OU=10gen Server }
154+
155+
156+
.. step:: Restart Secondary Cluster Members
157+
158+
.. include:: /includes/procedure-replica-set-restart-secondaries
159+
160+
Secondary servers in the replica set now use the new X.509 certificates.
161+
162+
.. step:: Restart Primary Cluster Member
163+
164+
.. include:: /includes/procedure-replica-set-restart-primary
165+
166+
The primary server in the replica set steps down and restarts as a
167+
secondary that uses the new X.509 certificate.
168+
169+
.. step:: Remove the DN Certification Override Configuration
170+
171+
With all members of the cluster now using the new X.509 certificate,
172+
update the configuration file to remove the :setting:`setParameter`
173+
settings for the :parameter:`tlsClusterAuthX509Override` parameter.
174+
175+
For example:
176+
177+
.. code-block:: yaml
178+
179+
net:
180+
tls:
181+
mode: requireTLS
182+
certificateKeyFile: /etc/mycerts/mongodb-server1.pem
183+
CAFile: /etc/mycerts/ca.pem
184+
clusterFile: /etc/mycerts/mongodb-cluster1.pem
185+
clusterCAFile: /etc/mycerts/ca.pem
186+
clusterAuthX509:
187+
attributes: O=MongoDB, OU=MongoDB Server
188+
security:
189+
clusterAuthMode: x509
190+
191+
This ensures that the server doesn't configure the old certificate
192+
settings on startup.
193+
194+
.. step:: Restart Secondary Cluster Members
195+
196+
.. include:: /includes/procedure-replica-set-restart-secondaries
197+
198+
Secondary servers in the replica set restart and no longer accept
199+
connections from the old X.509 certificates.
200+
201+
.. step:: Restart Primary Cluster Member
202+
203+
.. include:: /includes/procedure-replica-set-restart-primary
204+
205+
The primary server steps down and restarts as a secondary that no longer
206+
accepts connections from the old X.509 certificates.
207+
208+
Learn More
209+
----------
210+
211+
* :ref:`security-auth-x509`
212+
* :ref:`x509-internal-authentication`
213+
* :ref:`upgrade-to-x509-internal-authentication`

0 commit comments

Comments
 (0)