Skip to content

Commit 66069b8

Browse files
jocelyn-mendez1jocelyn-mendez1
authored
OIDC-docs merge feature branch into master (#3396)
* DOCSP-29121 OIDC Authentication (#3302) * DOCSP-29121 draft redo * DOCSP-29121 rework details * DOCSP-29121 fix links * DOCSP-29121 internal feedback * DOCSP-29121 external updates * DOCSP-29130 release notes (#3375) * DOCSP-29125 oidcIdentityProviders server parameter (#3319) * DOCSP-29125 configure mongodb for oidc * DOCSP-29125 server parameter * DOCSP-29125 fix table * DOCSP-29125 fix table * DOCSP-29125 fix table * DOCSP-29125 fix table * DOCSP-29125 fix table * DOCSP-29125 internal feedback * DOCSP-29125 typo fixes * DOCSP-29125 typo fix * DOCSP-29125 typo fix * DOCSP-29125 trying to get staging * DOCSP-29125 remove old fields * DOCSP-29125 external feedback * DOCSP-29125 external * DOCSP-29125 external * DOCSP-29125 external * DOCSP-29125 remove clientSecret * DOCSP-29125 fix ref * DOCSP-29125 nit fix * DOCSP-29123 OIDC task page (#3335) * DOCSP-29123 task page * DOCSP-29123 fix second step * DOCSP-29123 fix second step * DOCSP-29123 fix second step * DOCSP-29123 fixing new step * DOCSP-29123 update second step * DOCSP-29123 add link * DOCSP-29123 update refs * DOCSP-29123 update step * DOCSP-29123 update * DOCSP-29123 internal updates * DOCSP-29123 fixed ref * DOCSP-29123 add mongosh comment * DOCSP-29123 add tabs * DOCSP-29123 syntax fixes * DOCSP-29123 nit fix * DOCSP-29123 add toc tree * DOCSP-29123 add toc tree * DOCSP-29123 update ref * DOCSP-29123 updates * DOCSP-29124 OIDC in Authentication Page (#3391) * DOCSP-29124 create include and add oidc to auth * DOCSP-29124 create include and add oidc to auth * DOCSP-29124 fix ref * DOCSP-29124 fix ref * DOCSP-29124 internal feedback * DOCSP-29124 internal feedback * oidc-docs update link name * oidc-docs update ref
1 parent 0087588 commit 66069b8

File tree

11 files changed

+338
-1
lines changed

11 files changed

+338
-1
lines changed

‎snooty.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ toc_landing_pages = [
8181
"/core/security-internal-authentication",
8282
"/core/security-ldap",
8383
"/core/security-scram",
84+
"/core/security-oidc",
8485
"/core/security-transport-encryption",
8586
"/core/security-users",
8687
"/core/security-x.509",

‎source/core/authentication.txt‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Authentication
99
.. contents:: On this page
1010
:local:
1111
:backlinks: none
12-
:depth: 1
12+
:depth: 2
1313
:class: singlecol
1414

1515
Authentication is the process of verifying the identity of a client.
@@ -120,6 +120,19 @@ For more information on Kerberos and MongoDB, see:
120120
These mechanisms allow MongoDB to integrate into your
121121
existing authentication system.
122122

123+
OpenID Connect Authentication
124+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125+
126+
.. include:: /includes/fact-oidc-authentication.rst
127+
128+
For more information on OpenID Connect and MongoDB, see:
129+
130+
- :ref:`OpenID Connect Authentication <authentication-oidc>`
131+
132+
- :ref:`Configure MongoDB with OpenID Connect <configure-oidc>`
133+
134+
- `OpenID Connect <https://auth0.com/docs/authenticate/protocols/openid-connect-protocol>`_
135+
123136

124137
Internal / Membership Authentication
125138
------------------------------------
@@ -138,6 +151,7 @@ for more information.
138151
/core/security-x.509
139152
/core/kerberos
140153
/core/security-ldap
154+
/core/security-oidc
141155
/core/security-internal-authentication
142156
/core/localhost-exception
143157
/core/security-users

‎source/core/security-oidc.txt‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
.. _authentication-oidc:
2+
3+
=============================
4+
OpenID Connect Authentication
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+
.. include:: /includes/fact-oidc-authentication.rst
16+
17+
Behavior
18+
--------
19+
20+
- To authenticate using OpenID Connect, enable the ``MONGODB-OIDC`` :ref:`authentication
21+
mechanism <authentication>`.
22+
23+
- OpenID Connect uses access tokens to provide identity information. The access
24+
tokens are encoded as JSON Web Tokens (JWT). They contain information about
25+
user identities and authorization rights.
26+
27+
- MongoDB currently supports the use of Microsoft Azure AD and Okta as third-party
28+
identity providers.
29+
30+
Get Started
31+
-----------
32+
33+
- :ref:`Configure MongoDB with OpenID Connect <configure-oidc>`
34+
35+
Details
36+
-------
37+
38+
The OpenID Connect authentication process with MongoDB is summarized below:
39+
40+
1. Configure your MongoDB server with OpenID Connect. The configuration
41+
includes information from your identity provider, such as client ID,
42+
authorization endpoints, and token endpoints. For more details, see
43+
:ref:`Configure MongoDB with OpenID Connect <configure-oidc>`.
44+
45+
#. The client application (for example :binary:`~bin.mongosh` or |compass|)
46+
contacts the identity provider's authorization endpoint. You are redirected
47+
to your identity provider's login screen. Provide your credentials to complete
48+
authentication.
49+
50+
#. The client application receives an access token from the identity provider.
51+
52+
#. The MongoDB server uses the access token provided from the client application to
53+
finalize authentication. The access token contains information such as user
54+
identity and authorization rights.
55+
56+
Learn More
57+
----------
58+
59+
- `OpenID Connect <https://auth0.com/docs/authenticate/protocols/openid-connect-protocol>`_
60+
61+
- `Microsoft Azure AD <https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-oidc-sso>`_
62+
63+
- `Okta as an Identity Provider <https://help.okta.com/oie/en-us/Content/Topics/Apps/apps-about-oidc.htm>`_
64+
65+
.. toctree::
66+
:titlesonly:
67+
:hidden:
68+
69+
/tutorial/configure-oidc

‎source/includes/fact-oidc-authentication.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
MongoDB Enterprise supports OpenID Connect authentication. OpenID
2+
Connect is an authentication layer built on top of OAuth2. You can use OpenID
3+
Connect to configure single sign-on between your MongoDB database and a third-party
4+
identity provider.

‎source/includes/fact-oidc-providers.rst‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
.. list-table::
2+
:header-rows: 1
3+
:widths: 20 25 35 20
4+
5+
* - Field
6+
7+
- Necessity
8+
9+
- Description
10+
11+
- Type
12+
13+
* - ``issuer``
14+
15+
- Required
16+
17+
- The issuer URI of the IDP that the server should accept tokens from. This
18+
must match the ``iss`` field in any JWT used for authentication.
19+
20+
- string
21+
22+
* - ``authNamePrefix``
23+
24+
- Required
25+
26+
- Unique prefix applied to each generated ``UserName`` and ``RoleName`` used
27+
in authorization.
28+
29+
- string
30+
31+
* - ``matchPattern``
32+
33+
- Conditional
34+
35+
- Required when more than one IDP is defined.
36+
37+
Regex pattern used to determine which IDP should be used. ``matchPattern``
38+
matches against usernames. Array order determines the priority and the
39+
first IDP is always selected.
40+
41+
This is not a security mechanism. ``matchPattern`` serves only as an advisory
42+
to clients. MongoDB accepts tokens issued by the IDP whose principal
43+
names do not match this pattern.
44+
45+
- string
46+
47+
* - ``clientId``
48+
49+
- Required
50+
51+
- ID provided by the IDP to identify the client that receives the access tokens.
52+
53+
- string
54+
55+
* - ``audience``
56+
57+
- Required
58+
59+
- Specifies the application or service that the access token is intended for.
60+
61+
- string
62+
63+
* - ``requestScopes``
64+
65+
- Optional
66+
67+
- Permissions and access levels that MongoDB requests from the IDP.
68+
69+
- array[ string ]
70+
71+
* - ``principalName``
72+
73+
- Optional
74+
75+
- The claim to be extracted from the access token containing MongoDB user
76+
identifiers.
77+
78+
The default value is ``sub`` (stands for ``subject``).
79+
80+
- string
81+
82+
* - ``authorizationClaim``
83+
84+
- Required
85+
86+
- Claim extracted from access token that contains MongoDB role names.
87+
88+
- string
89+
90+
* - ``logClaims``
91+
92+
- Optional
93+
94+
- List of access token claims to include in log and audit messages upon
95+
authentication completion.
96+
97+
- array[ string ]
98+
99+
* - ``JWKSPollSecs``
100+
101+
- Optional
102+
103+
- Frequency, in seconds, to request an updated JSON Web Key Set (JWKS) from the IDP.
104+
A setting of 0 disables polling.
105+
106+
- integer

‎source/includes/list-table-auth-mechanisms.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,9 @@
3535
passwords in plain text. This mechanism is available only in
3636
`MongoDB Enterprise
3737
<http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server>`_.
38+
39+
* - :ref:`MONGODB-OIDC <authentication-oidc>`
40+
41+
- OpenID Connect is an authentication layer built on top of OAuth2. This mechanism
42+
is available only in `MongoDB Enterprise
43+
<http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server>`_.

‎source/reference/parameters.txt‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -428,6 +428,28 @@ Authentication Parameters
428428
can change this setting using the :dbcommand:`setParameter` database
429429
command.
430430

431+
.. parameter:: oidcIdentityProviders
432+
433+
.. versionadded:: 7.0
434+
435+
Use this parameter to specify identity provider (IDP) configurations when
436+
using :ref:`OpenID Connect Authentication <authentication-oidc>`.
437+
438+
``oidcIdentityProviders`` accepts an array of zero or more identity provider
439+
(IDP) configurations. An empty array (default) indicates no OpenID Connect
440+
support is enabled. When more than one IDP is defined, ``oidcIdentityProviders``
441+
uses the ``matchPattern`` field to select an IDP. Array order determines the
442+
priority and the first IDP is always selected.
443+
444+
oidcIdentityProviders Fields
445+
````````````````````````````
446+
447+
.. include:: /includes/fact-oidc-providers.rst
448+
449+
You can only set ``oidcIdentityProviders`` during startup in the
450+
:setting:`configuration file <setParameter>` or with the
451+
``--setParameter`` option on the command line.
452+
431453
.. parameter:: ocspEnabled
432454

433455
.. versionadded:: 4.4

‎source/release-notes/7.0.txt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,13 @@ parameter which lets you specify whether or not a set of :ref:`log messages
159159
<log-messages-ref>` related to cluster connection health metrics appears in the
160160
log.
161161

162+
``oidcIdentityProviders`` Parameter
163+
```````````````````````````````````
164+
165+
MongoDB 7.0 adds the :parameter:`oidcIdentityProviders` parameter which allows
166+
you to specify identity provider (IDP) configurations when using
167+
:ref:`OpenID Connect <authentication-oidc>` authentication.
168+
162169
Security
163170
~~~~~~~~
164171

@@ -174,6 +181,14 @@ OpenSSL and FIPS Support
174181

175182
For details, see :ref:`transport-encryption`.
176183

184+
OpenID Connect
185+
``````````````
186+
Starting in 7.0, MongoDB Enterprise provides support for
187+
:ref:`OpenID Connect <authentication-oidc>` authentication. OpenID Connect is an
188+
authentication layer built on top of OAuth2. You can use OpenID Connect to
189+
configure single sign-on between your MongoDB database and a third-party identity
190+
provider.
191+
177192
Aggregation
178193
-----------
179194

‎source/security.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@ security features include:
4949

5050
:doc:`/core/security-ldap`
5151

52+
:doc:`/core/security-oidc`
53+
5254
:doc:`/core/auditing`
5355

5456
:ref:`log-message-log-redaction`

0 commit comments

Comments
 (0)