DOCSP-47923: kubernetes oidc (#205)

Author: rustagir

examples/src/test/kotlin/EnterpriseAuthTest.kt

@@ -171,6 +171,32 @@ internal class EnterpriseAuthTest {
         // :snippet-end:
     }
 
+    fun oidcKubernetesConnectionString() = runBlocking {
+        // :snippet-start: oidc-k8s-connection-string
+        val connectionString = ConnectionString(
+            "mongodb://<OIDC principal>@<hostname>:<port>/?" +
+                    "authMechanism=MONGODB-OIDC" +
+                    "&authMechanismProperties=ENVIRONMENT:k8s,TOKEN_RESOURCE:<percent-encoded audience>")
+        val mongoClient = MongoClient.create(connectionString)
+        // :snippet-end:
+    }
+
+    fun oidcKubernetesCredential() = runBlocking {
+        // :snippet-start: oidc-k8s-credential
+        val credential = MongoCredential.createOidcCredential("<OIDC principal>")
+            .withMechanismProperty("ENVIRONMENT", "k8s")
+            .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
+
+        val mongoClient = MongoClient.create(
+            MongoClientSettings.builder()
+                .applyToClusterSettings { builder ->
+                    builder.hosts(listOf(ServerAddress("<hostname>", PORT)))
+                }
+                .credential(credential)
+                .build())
+        // :snippet-end:
+    }
+
     fun oidcCallback() = runBlocking {
         // :snippet-start: oidc-callback
         val credential = MongoCredential.createOidcCredential(null)

source/examples/generated/EnterpriseAuthTest.snippet.oidc-k8s-connection-string.kt

@@ -0,0 +1,5 @@
+val connectionString = ConnectionString(
+    "mongodb://<OIDC principal>@<hostname>:<port>/?" +
+            "authMechanism=MONGODB-OIDC" +
+            "&authMechanismProperties=ENVIRONMENT:k8s,TOKEN_RESOURCE:<percent-encoded audience>")
+val mongoClient = MongoClient.create(connectionString)

source/examples/generated/EnterpriseAuthTest.snippet.oidc-k8s-credential.kt

@@ -0,0 +1,11 @@
+val credential = MongoCredential.createOidcCredential("<OIDC principal>")
+    .withMechanismProperty("ENVIRONMENT", "k8s")
+    .withMechanismProperty("TOKEN_RESOURCE", "<audience>")
+
+val mongoClient = MongoClient.create(
+    MongoClientSettings.builder()
+        .applyToClusterSettings { builder ->
+            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
+        }
+        .credential(credential)
+        .build())

source/fundamentals/enterprise-auth.txt

@@ -224,7 +224,6 @@ to improve performance.
    - `JDK-6722928 <https://bugs.openjdk.java.net/browse/JDK-6722928>`__
    - `SO 23427343 <https://stackoverflow.com/questions/23427343/cannot-retrieve-tgt-despite-allowtgtsessionkey-registry-entry>`__
 
-
 .. _plain-auth-mechanism:
 
 LDAP (PLAIN)
@@ -396,6 +395,46 @@ see the corresponding syntax.
       .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-gcp-credential.kt
          :language: kotlin
 
+.. _kotlin-auth-kubernetes:
+
+Kubernetes
+++++++++++
+
+If your application runs on a Kubernetes cluster, you can authenticate
+to MongoDB by using the {+driver-short+}'s built-in Kubernetes support.
+
+Select from the :guilabel:`Connection String` or
+:guilabel:`MongoCredential` tabs to see the corresponding syntax.
+
+.. tabs::
+
+   .. tab:: Connection String
+      :tabid: mongodb-kubernetes-connection-string
+
+      To specify Kubernetes OIDC as the authentication mechanism, set the following 
+      options in your connection string:
+
+      - ``authMechanism``: Set to ``MONGODB-OIDC``.
+      - ``authMechanismProperties``: Set to ``ENVIRONMENT:k8s``. 
+
+      Replace the ``<percent-encoded audience>`` placeholder in the
+      following code with the percent-encoded value of the audience server
+      parameter configured on your MongoDB deployment.
+
+      .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-k8s-connection-string.kt
+         :language: kotlin
+
+   .. tab:: MongoCredential
+      :tabid: mongodb-kubernetes-mongo-credential
+
+      Replace the ``hostname`` and ``port`` with the network address and port 
+      number of your MongoDB deployment. Also, replace the
+      ``<audience>`` placeholder with the value of the ``audience``
+      server parameter configured on your MongoDB deployment.
+
+      .. literalinclude:: /examples/generated/EnterpriseAuthTest.snippet.oidc-k8s-credential.kt
+         :language: kotlin
+
 Custom Callback
 +++++++++++++++
 

source/whats-new.txt

@@ -39,6 +39,11 @@ and features:
       :ref:`kotlin-client-bulk-write-replace` sections of the Bulk
       Operations guide
 
+   .. replacement:: k8s-link
+
+      the :ref:`MONGODB-OIDC: Kubernetes <kotlin-auth-kubernetes>`
+      section of the Enterprise Authentication Mechanisms guide
+
 .. _kotlin-coroutine-version-5.3:
 
 What's New in 5.3