DRIVERS-2960: Clarify Reauthentication and Speculative Authentication combination behavior

source/auth/auth.md

@@ -1787,7 +1787,8 @@ def speculative_auth(connection):
 
 If any operation fails with `ReauthenticationRequired` (error code 391) and MONGODB-OIDC is in use, the driver MUST
 reauthenticate the connection. Drivers MUST NOT resend a `hello` message during reauthentication, instead using SASL
-messages directly. See the main [reauthentication](#reauthentication-1) section for more information.
+messages directly. Drivers MUST NOT try to use Speculative Authentication during reauthentication. See the main
+[reauthentication](#reauthentication-1) section for more information.
 
 To reauthenticate a connection, invalidate the access token stored on the connection (i.e. the *Connection Cache*) from
 the *Client Cache*, fetch a new access token, and re-run the SASL conversation.
@@ -2041,6 +2042,8 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p
 
 ## Changelog
 
+- 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.
 
 - 2024-05-03: Clarify timeout behavior for OIDC machine callback. Add `serverless:forbid` to OIDC unified tests. Add an

source/auth/tests/mongodb-oidc.md

@@ -129,7 +129,7 @@ source the `secrets-export.sh` file and use the associated env variables in your
 
 ### (4) Reauthentication
 
-\*\*4.1 Reauthentication Succeeds
+#### 4.1 Reauthentication Succeeds
 
 - Create an OIDC configured client.
 - Set a fail point for `find` commands of the form:
@@ -153,7 +153,7 @@ source the `secrets-export.sh` file and use the associated env variables in your
 - Assert that the callback was called 2 times (once during the connection handshake, and again during reauthentication).
 - Close the client.
 
-\*\*4.2 Read Commands Fail If Reauthentication Fails
+#### 4.2 Read Commands Fail If Reauthentication Fails
 
 - Create a `MongoClient` whose OIDC callback returns one good token and then bad tokens after the first call.
 - Perform a `find` operation that succeeds.
@@ -203,6 +203,35 @@ source the `secrets-export.sh` file and use the associated env variables in your
 - Assert that the callback was called 2 times.
 - Close the client.
 
+#### 4.4 Speculative Authentication should be ignored on Reauthentication
+
+- Create an OIDC configured client.
+- Populate the *Client Cache* with a valid access token to enforce Speculative Authentication.
+- Perform an `insert` operation that succeeds.
+- Assert that the callback was not called.
+- Assert there were no `SaslStart` commands executed.
+- Set a fail point for `insert` commands of the form:
+
+```javascript
+{
+  configureFailPoint: "failCommand",
+  mode: {
+    times: 1
+  },
+  data: {
+    failCommands: [
+      "insert"
+    ],
+    errorCode: 391 // ReauthenticationRequired
+  }
+}
+```
+
+- Perform an `insert` operation that succeeds.
+- Assert that the callback was called once.
+- Assert there were `SaslStart` commands executed.
+- Close the client.
+
 ## (5) Azure Tests
 
 Drivers MUST only run the Azure tests when testing on an Azure VM. See instructions in