DRIVERS-2882 Add Kubernetes Support for OIDC (#1622)

Author: blink1073

.pre-commit-config.yaml

@@ -76,7 +76,7 @@ repos:
   rev: "v2.3.0"
   hooks:
   - id: codespell
-    args: ["-L", "fle,re-use,merchantibility,synching,crate,nin,infinit,te,checkin"]
+    args: ["-L", "fle,re-use,merchantibility,synching,crate,nin,infinit,te,checkin,aks"]
     exclude: |
             (?x)^(.*\.rst
             )$

source/auth/auth.md

@@ -1266,8 +1266,8 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall
     - ENVIRONMENT
 
         Drivers MUST allow the user to specify the name of a built-in OIDC application environment integration to use to
-        obtain credentials. If provided, the value MUST be one of `["test", "azure", "gcp"]`. If both `ENVIRONMENT` and an
-        [OIDC Callback](#oidc-callback) or [OIDC Human Callback](#oidc-human-callback) are provided for the same
+        obtain credentials. If provided, the value MUST be one of `["test", "azure", "gcp", "k8s"]`. If both `ENVIRONMENT`
+        and an [OIDC Callback](#oidc-callback) or [OIDC Human Callback](#oidc-human-callback) are provided for the same
         `MongoClient`, the driver MUST raise an error.
 
     - TOKEN_RESOURCE
@@ -1428,6 +1428,35 @@ callback had been provided by the user.
 For details on test environment setup, see the README in
 [Drivers-Evergreen-Tools](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/gcp/README.md).
 
+***Kubernetes***
+
+The Kubernetes integration is enabled by setting auth mechanism property `ENVIRONMENT:k8s`. In this configuration, the
+driver is expected to be running inside a Kubernetes environment with a configured
+[ServiceAccount](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/#bound-service-account-token-volume).
+
+If enabled, drivers MUST read the contents of the token from the local file path found using the following algorithm:
+
+```python
+if 'AZURE_FEDERATED_TOKEN_FILE' in os.environ:
+  fname = os.environ['AZURE_FEDERATED_TOKEN_FILE']
+elif 'AWS_WEB_IDENTITY_TOKEN_FILE' in os.environ:
+  fname = os.environ['AWS_WEB_IDENTITY_TOKEN_FILE']
+else:
+  fname = '/var/run/secrets/kubernetes.io/serviceaccount/token'
+```
+
+Where `AZURE_FEDERATED_TOKEN_FILE` contains the file path on Azure Kubernetes Service (AKS),
+`AWS_WEB_IDENTITY_TOKEN_FILE` contains the file path on Elastic Kubernetes Service (EKS), and
+`/var/run/secrets/kubernetes.io/serviceaccount/token` is the default path for a Kubernetes
+[ServiceAccount token](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/#serviceaccount-admission-controller),
+which is used by Google Kubernetes Engine (GKE).
+
+The callback itself MUST not perform any caching, and the driver MUST cache its tokens in the same way as if a custom
+callback had been provided by the user.
+
+For details on test environment setup, see the README in
+[Drivers-Evergreen-Tools](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/k8s/README.md).
+
 #### OIDC Callback
 
 Drivers MUST allow users to provide a callback that returns an OIDC access token. The purpose of the callback is to
@@ -2105,6 +2134,8 @@ practice to avoid this. (See
 
 ## Changelog
 
+- 2024-10-02: Add Kubernetes built-in OIDC provider integration.
+
 - 2024-08-19: Clarify Reauthentication and Speculative Authentication combination behavior.
 
 - 2024-05-29: Disallow comma character when `TOKEN_RESOURCE` is given in a connection string.

source/auth/tests/legacy/connection-string.json

@@ -454,3 +454,18 @@ tests:
   uri: mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp
   valid: false
   credential: null
+- description: should recognise the mechanism with k8s provider (MONGODB-OIDC)
+  uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:k8s
+  valid: true
+  credential:
+    username: null
+    password: null
+    source: $external
+    mechanism: MONGODB-OIDC
+    mechanism_properties:
+      ENVIRONMENT: k8s
+- description: should throw an error for a username and password with k8s provider
+    (MONGODB-OIDC)
+  uri: mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:k8s
+  valid: false
+  credential: null

source/auth/tests/legacy/connection-string.yml

@@ -21,7 +21,7 @@ ______________________________________________________________________
 Drivers MUST run the machine prose tests when `OIDC_TOKEN_DIR` is set. Drivers can either set the `ENVIRONMENT:test`
 auth mechanism property, or use a custom callback that also reads the file.
 
-Drivers can also choose to run the machine prose tests on GCP or Azure VMs.
+Drivers can also choose to run the machine prose tests on GCP or Azure VMs, or on the Kubernetes clusters.
 
 Drivers MUST implement all prose tests in this section. Unless otherwise noted, all `MongoClient` instances MUST be
 configured with `retryReads=false`.