DRIVERS-2836 OIDC Spec Cleanup

source/auth/auth.md

@@ -1647,8 +1647,8 @@ Use the following algorithm to authenticate a new connection:
 
 - Check if the the *Client Cache* has an access token.
   - If it does, cache the access token in the *Connection Cache* and perform a `One-Step` SASL conversation using the
-    access token in the *Client Cache*. If the server returns an error, invalidate that access token, sleep 100ms then
-    continue.
+    access token in the *Client Cache*. If the server returns a Authentication error (18), invalidate that access token,
+    sleep 100ms then continue.
 - Call the configured built-in provider integration or the OIDC callback to retrieve a new access token.
 - Cache the new access token in the *Client Cache* and *Connection Cache*.
 - Perform a `One-Step` SASL conversation using the new access token. Raise any errors to the user.
@@ -1660,18 +1660,21 @@ def auth(connection):
   access_token, is_cache = get_access_token()
 
   # If there is a cached access token, try to authenticate with it. If
-  # authentication fails, it's possible the cached access token is expired. In
+  # authentication fails with an Authentication error (18), 
+  # it's possible the cached access token is expired. In
   # that case, invalidate the access token, fetch a new access token, and try
   # to authenticate again.
+  # If the server fails for any other reason, do not clear the cache.
   if is_cache:
     try:
       connection.oidc_cache.access_token = access_token
       sasl_start(connection, payload={"jwt": access_token})
       return
-    except ServerError:
-      invalidate(access_token)
-      sleep(0.1)
-      access_token, _ = get_access_token()
+    except ServerError as e:
+      if e.code == 18:
+        invalidate(access_token)
+        sleep(0.1)
+        access_token, _ = get_access_token()
 
   connection.oidc_cache.access_token = access_token
   sasl_start(connection, payload={"jwt": access_token})
@@ -1682,14 +1685,15 @@ authenticate a new connection when a [OIDC Human Callback](#oidc-human-callback)
 
 - Check if the *Client Cache* has an access token.
   - If it does, cache the access token in the *Connection Cache* and perform a [One-Step](#one-step) SASL conversation
-    using the access token. If the server returns an error, invalidate the access token token from the *Client Cache*,
-    clear the *Connection Cache*, and continue.
+    using the access token. If the server returns an Authentication error (18), invalidate the access token token from
+    the *Client Cache*, clear the *Connection Cache*, and continue. If the server returns another error, continue.
 - Check if the *Client Cache* has a refresh token.
   - If it does, call the [OIDC Human Callback](#oidc-human-callback) with the cached refresh token and `IdpInfo` to get
     a new access token. Cache the new access token in the *Client Cache* and *Connection Cache*. Perform a
     [One-Step](#one-step) SASL conversation using the new access token. If the
-    [OIDC Human Callback](#oidc-human-callback) or the server return an error, invalidate the access token from the
-    *Client Cache*, clear the *Connection Cache*, and continue.
+    [OIDC Human Callback](#oidc-human-callback) or the server returns an Authentication error (18), invalidate the
+    access token from the *Client Cache*, clear the *Connection Cache*, and continue. If the server returns another
+    error, continue.
 - Start a new [Two-Step](#two-step) SASL conversation.
 - Run a `PrincipalStepRequest` to get the `IdpInfo`.
 - Call the [OIDC Human Callback](#oidc-human-callback) with the new `IdpInfo` to get a new access token and optional
@@ -1988,6 +1992,8 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p
 
 ## Changelog
 
+- 2024-03-21: Specify to only invalidate cached OIDC access tokens if the server returns error 18.
+
 - 2024-03-21: Added Azure built-in OIDC provider integration.
 
 - 2024-03-09: Rename OIDC integration name and values.

source/auth/tests/mongodb-oidc.md

@@ -103,6 +103,32 @@ method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI`.
 - Assert that the callback was called 1 time.
 - Close the client.
 
+**3.3 Unexpected error code does not clear the cache**
+
+- Create a `MongoClient` with a human callback that returns a valid token.
+- Set a fail point for `saslStart` commands of the form:
+
+```javascript
+{
+  configureFailPoint: "failCommand",
+  mode: {
+    times: 1
+  },
+  data: {
+    failCommands: [
+      "saslStart"
+    ],
+    errorCode: 20 // IllegalOperation
+  }
+}
+```
+
+- Perform a `find` operation that fails.
+- Assert that the human callback has been called once.
+- Perform a `find` operation that succeeds.
+- Assert that the human callback has been called once.
+- Close the client.
+
 ### (4) Reauthentication
 
 - Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic.
@@ -233,13 +259,38 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
   including the timeout parameter if possible.
 - Close the client.
 
-**2.3 Human Callback Returns Missing Data**
+**2.2 Human Callback Returns Missing Data**
 
 - Create a `MongoClient` with a human callback that returns data not conforming to the `OIDCCredential` with missing
   fields.
 - Perform a `find` operation that fails.
 - Close the client.
 
+**2.3 Refresh Token Is Passed To The Callback**
+
+- Create a `MongoClien`t with a human callback that checks for the presence of a refresh token.
+- Perform a find operation that succeeds.
+- Set a fail point for `find` commands of the form:
+
+```javascript
+{
+  configureFailPoint: "failCommand",
+  mode: {
+    times: 1
+  },
+  data: {
+    failCommands: [
+      "find"
+    ],
+    errorCode: 391
+  }
+}
+```
+
+- Perform a `find` operation that succeeds.
+- Assert that the callback has been called twice.
+- Assert that the refresh token was used once.
+
 ### (3) Speculative Authentication
 
 **3.1 Uses speculative authentication if there is a cached token**
@@ -268,12 +319,14 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 ```javascript
 {
   configureFailPoint: "failCommand",
-  mode: "alwaysOn",
+  mode: {
+    times: 1
+  },
   data: {
     failCommands: [
       "saslStart"
     ],
-    errorCode: 20
+    errorCode: 18
   }
 }
 ```
@@ -289,12 +342,14 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 ```javascript
 {
   configureFailPoint: "failCommand",
-  mode: "alwaysOn",
+  mode: {
+    times: 1
+  },
   data: {
     failCommands: [
       "saslStart"
     ],
-    errorCode: 20 // IllegalOperation
+    errorCode: 18
   }
 }
 ```
@@ -365,7 +420,7 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 
 **4.3 Succeeds after refresh fails**
 
-- Create a default OIDC client.
+- Create a default client with a callback that returns the `test_user1` access token and a bad refresh token.
 - Perform a `find` operation that succeeds.
 - Assert that the human callback has been called once.
 - Force a reauthenication using a fail point of the form:

source/auth/tests/unified/mongodb-oidc-no-retry.yml

@@ -173,11 +173,12 @@ tests:
       client: failPointClient
       failPoint:
         configureFailPoint: failCommand
-        mode: "alwaysOn"
+        mode:
+          times: 1
         data:
           failCommands:
           - saslStart
-          errorCode: 20 # IllegalOperation
+          errorCode: 18
   - name: insertOne
     object: collection0
     arguments:
@@ -211,19 +212,20 @@ tests:
       client: failPointClient
       failPoint:
         configureFailPoint: failCommand
-        mode: "alwaysOn"
+        mode: 
+          times: 1
         data:
           failCommands:
           - saslStart
-          errorCode: 20 # IllegalOperation
+          errorCode: 18
   - name: insertOne
     object: collection0
     arguments:
       document:
         _id: 1
         x: 1
     expectError:
-      errorCode: 20 # IllegalOperation
+      errorCode: 18
 - description: Read commands should fail if reauthentication fails
   operations:
   - name: find