OIDC-docs merge feature branch into master (#3396)

jocelyn-mendez1 · web-flow · commit 66069b8c8cea · 2023-06-21T12:57:32.000-04:00
* 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
diff --git a/snooty.toml b/snooty.toml
@@ -81,6 +81,7 @@ toc_landing_pages = [
    "/core/security-internal-authentication",
    "/core/security-ldap",
    "/core/security-scram",
+   "/core/security-oidc",
    "/core/security-transport-encryption",
    "/core/security-users",
    "/core/security-x.509",
diff --git a/source/core/authentication.txt b/source/core/authentication.txt
@@ -9,7 +9,7 @@ Authentication
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2 
    :class: singlecol
 
 Authentication is the process of verifying the identity of a client.
@@ -120,6 +120,19 @@ For more information on Kerberos and MongoDB, see:
 These mechanisms allow MongoDB to integrate into your
 existing authentication system.
 
+OpenID Connect Authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-oidc-authentication.rst 
+
+For more information on OpenID Connect and MongoDB, see:
+
+- :ref:`OpenID Connect Authentication <authentication-oidc>`
+
+- :ref:`Configure MongoDB with OpenID Connect <configure-oidc>` 
+
+- `OpenID Connect <https://auth0.com/docs/authenticate/protocols/openid-connect-protocol>`_  
+
 
 Internal / Membership Authentication
 ------------------------------------
@@ -138,6 +151,7 @@ for more information.
    /core/security-x.509
    /core/kerberos
    /core/security-ldap
+   /core/security-oidc
    /core/security-internal-authentication
    /core/localhost-exception
    /core/security-users
diff --git a/source/core/security-oidc.txt b/source/core/security-oidc.txt
@@ -0,0 +1,69 @@
+.. _authentication-oidc:
+
+=============================
+OpenID Connect Authentication
+=============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. include:: /includes/fact-oidc-authentication.rst
+
+Behavior
+--------
+
+- To authenticate using OpenID Connect, enable the ``MONGODB-OIDC`` :ref:`authentication 
+  mechanism <authentication>`. 
+
+- OpenID Connect uses access tokens to provide identity information. The access 
+  tokens are encoded as JSON Web Tokens (JWT). They contain information about 
+  user identities and authorization rights. 
+
+- MongoDB currently supports the use of Microsoft Azure AD and Okta as third-party 
+  identity providers.
+
+Get Started
+-----------
+
+- :ref:`Configure MongoDB with OpenID Connect <configure-oidc>`
+
+Details
+-------
+
+The OpenID Connect authentication process with MongoDB is summarized below: 
+
+1. Configure your MongoDB server with OpenID Connect. The configuration 
+   includes information from your identity provider, such as client ID, 
+   authorization endpoints, and token endpoints. For more details, see
+   :ref:`Configure MongoDB with OpenID Connect <configure-oidc>`.
+
+#. The client application (for example :binary:`~bin.mongosh` or |compass|) 
+   contacts the identity provider's authorization endpoint. You are redirected 
+   to your identity provider's login screen. Provide your credentials to complete 
+   authentication.
+
+#. The client application receives an access token from the identity provider.
+
+#. The MongoDB server uses the access token provided from the client application to 
+   finalize authentication. The access token contains information such as user 
+   identity and authorization rights. 
+
+Learn More
+----------
+
+- `OpenID Connect <https://auth0.com/docs/authenticate/protocols/openid-connect-protocol>`_ 
+
+- `Microsoft Azure AD <https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-oidc-sso>`_
+
+- `Okta as an Identity Provider <https://help.okta.com/oie/en-us/Content/Topics/Apps/apps-about-oidc.htm>`_ 
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   /tutorial/configure-oidc
diff --git a/source/includes/fact-oidc-authentication.rst b/source/includes/fact-oidc-authentication.rst
@@ -0,0 +1,4 @@
+MongoDB Enterprise supports OpenID Connect authentication. OpenID 
+Connect is an authentication layer built on top of OAuth2. You can use OpenID 
+Connect to configure single sign-on between your MongoDB database and a third-party 
+identity provider.
diff --git a/source/includes/fact-oidc-providers.rst b/source/includes/fact-oidc-providers.rst
@@ -0,0 +1,106 @@
+.. list-table::
+  :header-rows: 1
+  :widths: 20 25 35 20
+
+  * - Field
+
+    - Necessity
+
+    - Description
+
+    - Type
+
+  * - ``issuer``
+    
+    - Required
+
+    - The issuer URI of the IDP that the server should accept tokens from. This 
+      must match the ``iss`` field in any JWT used for authentication. 
+    
+    - string
+
+  * - ``authNamePrefix``
+
+    - Required
+
+    - Unique prefix applied to each generated ``UserName`` and ``RoleName`` used 
+      in authorization. 
+
+    - string
+
+  * - ``matchPattern``
+
+    - Conditional
+
+    - Required when more than one IDP is defined.
+
+      Regex pattern used to determine which IDP should be used. ``matchPattern`` 
+      matches against usernames. Array order determines the priority and the 
+      first IDP is always selected. 
+
+      This is not a security mechanism. ``matchPattern`` serves only as an advisory 
+      to clients. MongoDB accepts tokens issued by the IDP whose principal 
+      names do not match this pattern.
+
+    - string
+
+  * - ``clientId``
+
+    - Required 
+     
+    - ID provided by the IDP to identify the client that receives the access tokens.
+    
+    - string 
+
+  * - ``audience``
+
+    - Required
+
+    - Specifies the application or service that the access token is intended for.
+    
+    - string 
+
+  * - ``requestScopes``
+
+    - Optional
+     
+    - Permissions and access levels that MongoDB requests from the IDP.
+
+    - array[ string ] 
+    
+  * - ``principalName``
+    
+    - Optional 
+
+    - The claim to be extracted from the access token containing MongoDB user 
+      identifiers. 
+
+      The default value is ``sub`` (stands for ``subject``). 
+
+    - string 
+
+  * - ``authorizationClaim`` 
+
+    - Required 
+
+    - Claim extracted from access token that contains MongoDB role names.
+
+    - string  
+
+  * - ``logClaims``
+
+    - Optional
+
+    - List of access token claims to include in log and audit messages upon 
+      authentication completion.
+
+    - array[ string ]
+
+  * - ``JWKSPollSecs``
+
+    - Optional
+
+    - Frequency, in seconds, to request an updated JSON Web Key Set (JWKS) from the IDP. 
+      A setting of 0 disables polling.
+
+    - integer
diff --git a/source/includes/list-table-auth-mechanisms.rst b/source/includes/list-table-auth-mechanisms.rst
@@ -35,3 +35,9 @@
        passwords in plain text. This mechanism is available only in
        `MongoDB Enterprise
        <http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server>`_.
+
+   * - :ref:`MONGODB-OIDC <authentication-oidc>`
+
+     - OpenID Connect is an authentication layer built on top of OAuth2. This mechanism 
+       is available only in `MongoDB Enterprise
+       <http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server>`_.
diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt
@@ -428,6 +428,28 @@ Authentication Parameters
    can change this setting using the :dbcommand:`setParameter` database
    command.
 
+.. parameter:: oidcIdentityProviders
+
+   .. versionadded:: 7.0
+
+   Use this parameter to specify identity provider (IDP) configurations when 
+   using :ref:`OpenID Connect Authentication <authentication-oidc>`.
+
+   ``oidcIdentityProviders`` accepts an array of zero or more identity provider 
+   (IDP) configurations. An empty array (default) indicates no OpenID Connect 
+   support is enabled. When more than one IDP is defined, ``oidcIdentityProviders`` 
+   uses the ``matchPattern`` field to select an IDP. Array order determines the 
+   priority and the first IDP is always selected.  
+
+   oidcIdentityProviders Fields
+   ````````````````````````````
+
+   .. include:: /includes/fact-oidc-providers.rst
+
+   You can only set ``oidcIdentityProviders`` during startup in the
+   :setting:`configuration file <setParameter>` or with the
+   ``--setParameter`` option on the command line. 
+
 .. parameter:: ocspEnabled
 
    .. versionadded:: 4.4
diff --git a/source/release-notes/7.0.txt b/source/release-notes/7.0.txt
@@ -159,6 +159,13 @@ parameter which lets you specify whether or not a set of :ref:`log messages
 <log-messages-ref>` related to cluster connection health metrics appears in the 
 log.
 
+``oidcIdentityProviders`` Parameter
+```````````````````````````````````
+
+MongoDB 7.0  adds the :parameter:`oidcIdentityProviders` parameter which allows 
+you to specify identity provider (IDP) configurations when using 
+:ref:`OpenID Connect <authentication-oidc>` authentication. 
+
 Security
 ~~~~~~~~
 
@@ -174,6 +181,14 @@ OpenSSL and FIPS Support
 
 For details, see :ref:`transport-encryption`.
 
+OpenID Connect
+``````````````
+Starting in 7.0, MongoDB Enterprise provides support for 
+:ref:`OpenID Connect <authentication-oidc>` authentication. OpenID Connect is an 
+authentication layer built on top of OAuth2. You can use OpenID Connect to 
+configure single sign-on between your MongoDB database and a third-party identity 
+provider.
+
 Aggregation
 -----------
 
diff --git a/source/security.txt b/source/security.txt
@@ -49,6 +49,8 @@ security features include:
 
        :doc:`/core/security-ldap`
 
+       :doc:`/core/security-oidc`
+
        :doc:`/core/auditing`
 
        :ref:`log-message-log-redaction`
diff --git a/source/tutorial/configure-oidc.txt b/source/tutorial/configure-oidc.txt
diff --git a/source/tutorial/enable-authentication.txt b/source/tutorial/enable-authentication.txt
