DOCSP-34479 - OIDC

source/fundamentals/auth.txt

@@ -574,4 +574,4 @@ mechanism:
 
 For additional information on configuring your application to use
 certificates as well as TLS/SSL options, see our
-:doc:`TLS/SSL guide </fundamentals/connection/tls>`.
+:doc:`TLS/SSL guide </fundamentals/connection/tls>`.

source/fundamentals/enterprise-auth.txt

@@ -10,6 +10,13 @@ Enterprise Authentication Mechanisms
    :depth: 2
    :class: singlecol
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: ldap, encryption, principal, tls
+
 Overview
 --------
 
@@ -22,13 +29,13 @@ Enterprise Edition:
 
 - :ref:`Kerberos (GSSAPI) <gssapi-auth-mechanism>`
 - :ref:`LDAP (PLAIN) <plain-auth-mechanism>`
+- :ref:`MONGODB-OIDC <mongodb-oidc>`
 
 To authenticate using another mechanism, see the
 :doc:`Authentication Mechanisms guide </fundamentals/auth>`. For more
 information on establishing a connection to your MongoDB cluster, read our
 :doc:`Connection Guide </fundamentals/connection>`.
 
-
 Specify an Authentication Mechanism
 -----------------------------------
 
@@ -280,3 +287,154 @@ mechanism:
       method. The code to instantiate a ``MongoClient`` resembles the following:
 
       .. include:: /includes/fundamentals/code-snippets/auth-credentials-ldap.rst
+
+.. _mongodb-oidc:
+
+MONGODB-OIDC
+~~~~~~~~~~~~
+
+.. important::
+
+   The MONGODB-OIDC authentication mechanism requires {+mdb-server+} v7.0 or later running
+   on a Linux platform.
+
+The following sections describe how to use the MONGODB-OIDC authentication mechanism to
+authenticate to various platforms.
+
+For more information about the MONGODB-OIDC authentication mechanism, see
+:manual:`OpenID Connect Authentication </core/security-oidc/>` in the MongoDB Server
+manual.
+
+.. _java-mongodb-oidc-azure-imds:
+
+Azure IMDS
+++++++++++
+
+If your application runs on an Azure VM, or otherwise uses the
+`Azure Instance Metadata Service <https://learn.microsoft.com/en-us/azure/virtual-machines/instance-metadata-service>`__
+(IMDS), you can authenticate to MongoDB by using the {+driver-short+}'s built-in Azure
+support.
+
+You can specify Azure IMDS OIDC authentication either by 
+using a ``MongoCredential`` object or as part of the connection string. Select the 
+:guilabel:`Connection String` or :guilabel:`MongoCredential` tab to
+see the corresponding syntax.
+
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: mongodb-azure-imds-connection-string
+
+      Replace the ``<resource>`` placeholder with the percent-encoded application or
+      service that the OIDC access token is intended for.
+
+      .. code-block:: java
+
+         MongoClient mongoClient = MongoClients.create("mongodb://<username>@<hostname>:<port>/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<resource>");
+
+   .. tab:: MongoCredential
+      :tabid: mongodb-azure-mongo-credential
+
+      Replace the ``<username>`` placeholder with the client ID or application ID of the
+      Azure managed identity or enterprise application. Replace the ``<resource>``
+      placeholder with the application or service that the OIDC access token is intended for.
+      You must percent-encode the resource value
+      if it contains a comma (``,``), plus sign (``+``), or ampersand (``&``). 
+
+      .. code-block:: java
+
+         MongoCredential credential = MongoCredential.createOidcCredential("<username>")
+            .withMechanismProperty("TOKEN_RESOURCE", "<resource>")
+            .withMechanismProperty("ENVIRONMENT", "azure");  
+
+         MongoClient mongoClient = MongoClients.create(
+             MongoClientSettings.builder()
+                 .applyToClusterSettings(builder ->
+                         builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+                 .credential(credential)
+                 .build());
+
+.. _java-mongodb-oidc-gcp-imds:
+
+GCP IMDS
+++++++++++
+
+If your application runs on a GCP VM, or otherwise uses the
+`GCP Instance Metadata Service <https://cloud.google.com/compute/docs/metadata/querying-metadata>`__,
+you can authenticate to MongoDB by using {+driver-short+}'s built-in GCP
+support.
+
+You can specify GCP IMDS OIDC authentication either by 
+using a ``MongoCredential`` object or as part of the connection string. Select the 
+:guilabel:`Connection String` or :guilabel:`MongoCredential` tab to
+see the corresponding syntax.
+
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: mongodb-gcp-imds-connection-string
+
+      Replace the ``<resource>`` placeholder with the percent-encoded application or
+      service that the OIDC access token is intended for.
+
+      .. code-block:: java
+
+         MongoClient mongoClient = MongoClients.create("mongodb://<username>@<hostname>:<port>/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<resource>");
+
+   .. tab:: MongoCredential
+      :tabid: mongodb-gcp-mongo-credential
+
+      Replace the ``<username>`` placeholder with the client ID of the GCP managed
+      identity. Replace the ``<resource>`` placeholder with the
+      application or service that the OIDC access token is intended for.
+      You must percent-encode the resource value
+      if it contains a comma (``,``), plus sign (``+``), or ampersand (``&``). 
+
+      .. code-block:: java
+
+         MongoCredential credential = MongoCredential.createOidcCredential("<username>")
+            .withMechanismProperty("TOKEN_RESOURCE", "<resource>")
+            .withMechanismProperty("ENVIRONMENT", "gcp");  
+
+         MongoClient mongoClient = MongoClients.create(
+             MongoClientSettings.builder()
+                 .applyToClusterSettings(builder ->
+                         builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+                 .credential(credential)
+                 .build());
+
+Custom Callback
++++++++++++++++
+
+On some platforms, such as Azure Functions and Azure Kubernetes Service (AKS), you
+must define a custom callback method to use OIDC to authenticate. To use a custom
+callback to retrieve an OIDC token, call the ``withMechanismProperty()`` method on
+your ``MongoCredential`` object to set the following options:
+
+- ``"ALLOWED_HOSTS"``: The list of allowed hostnames or IP addresses for MongoDB.
+  The hostnames may include ``"*."`` as a leading wildcard, which allows for
+  matching subdomains. By default, this property includes ``"*.mongodb.net"``,
+  ``"*.mongodb-qa.net"``, ``"*.mongodb-dev.net"``, ``"*.mongodbgov.net"``, ``"localhost"``,
+  ``"127.0.0.1"``, and ``"::1"``.
+- ``"OIDC_CALLBACK"``: The method that retrieves the OIDC token. This method must accept
+  a ``context`` object as a parameter and return an ``OidcCallbackResult`` object.
+
+The following code example shows how to include
+a callback method in your ``MongoCredential`` object. In this example, the callback
+retrieves an OIDC token from a file named ``"access-token.dat"`` in the local file system.
+
+.. code-block:: java
+
+   MongoCredential credential = new Credential()
+      .withMechanismProperty("ALLOWED_HOSTS", allowedHosts)
+      .withMechanismProperty("OIDC_CALLBACK", (context) ->  {
+         string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat"));
+         return new OidcCallbackResult(accessToken, 0);
+      });
+
+   MongoClient mongoClient = MongoClients.create(
+       MongoClientSettings.builder()
+           .applyToClusterSettings(builder ->
+                   builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
+           .credential(credential)
+           .build());