DRIVERS-2878 OIDC Atlas Testing Updates (#1558)

Author: blink1073

source/auth/auth.md

@@ -1220,8 +1220,8 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall
 
   - TOKEN_RESOURCE\
     The URI of the target resource. This property is currently only used and required by the Azure
-    built-in OIDC provider integration. If `TOKEN_RESOURCE` is provided and `PROVIDER_NAME` is not `azure` or
-    `TOKEN_RESOURCE` is not provided and `PROVIDER_NAME` is `azure`, the driver MUST raise an error.
+    built-in OIDC provider integration. If `TOKEN_RESOURCE` is provided and `ENVIRONMENT` is not `azure` or
+    `TOKEN_RESOURCE` is not provided and `ENVIRONMENT` is `azure`, the driver MUST raise an error.
 
   - OIDC_CALLBACK\
     An [OIDC Callback](#oidc-callback) that returns OIDC credentials. Drivers MAY allow the user to
@@ -1988,6 +1988,8 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p
 
 ## Changelog
 
+- 2024-03-29: Updated OIDC test setup and descriptions.
+
 - 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

@@ -2,20 +2,9 @@
 
 ## Local Testing
 
-To test locally, use the
-[oidc_get_tokens.sh](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/oidc_get_tokens.sh)
-script from [drivers-evergreen-tools](https://github.com/mongodb-labs/drivers-evergreen-tools/) to download a set of
-OIDC tokens, including `test_user1` and `test_user1_expires`. You first have to install the AWS CLI and login using the
-SSO flow.
-
-For example, if the selected AWS profile ID is "drivers-test", run:
-
-```shell
-aws configure sso
-export OIDC_TOKEN_DIR=/tmp/tokens
-AWS_PROFILE="drivers-test" oidc_get_tokens.sh
-OIDC_TOKEN_FILE="$OIDC_TOKEN_DIR/test_user1" /my/test/command
-```
+See the detailed instructions in
+[drivers-evergreen-tools](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/README.md)
+for how to set up your environment for OIDC testing.
 
 ______________________________________________________________________
 
@@ -36,25 +25,25 @@ Drivers MUST run the prose tests in all supported OIDC environments.
 > For test cases that create fail points, drivers MUST either use a unique `appName` or explicitly remove the fail point
 > callback to prevent interaction between test cases.
 
-Note that typically the preconfigured Atlas Dev clusters are used for testing, in Evergreen and locally. The URIs can be
-fetched from the `drivers/oidc` Secrets vault, see
-[vault instructions](https://wiki.corp.mongodb.com/display/DRIVERS/Using+AWS+Secrets+Manager+to+Store+Testing+Secrets).
-Use `OIDC_ATLAS_URI_SINGLE` for the `MONGODB_URI`. If using local servers is preferred, using the
-[Local Testing](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/README.md#local-testing)
-method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI`.
+After setting up your OIDC
+[environment](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/README.md),
+source the `secrets-export.sh` file and use the associated env variables in your tests.
+
+An OIDC configured client MUST set the appropriate `ENVIRONMENT` auth mechanism property and include a callback that
+gets the appropriate token for the given environment.
 
 ### Callback Authentication
 
 **1.1 Callback is called during authentication**
 
-- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic.
+- Create an OIDC configured client.
 - Perform a `find` operation that succeeds.
 - Assert that the callback was called 1 time.
 - Close the client.
 
 **1.2 Callback is called once for multiple connections**
 
-- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic.
+- Create an OIDC configured client.
 - Start 10 threads and run 100 `find` operations in each thread that all succeed.
 - Assert that the callback was called 1 time.
 - Close the client.
@@ -63,49 +52,49 @@ method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI`.
 
 **2.1 Valid Callback Inputs**
 
-- Create a `MongoClient` configured with an OIDC callback that validates its inputs and returns a valid access token.
+- Create an OIDC configured client with an OIDC callback that validates its inputs and returns a valid access token.
 - Perform a `find` operation that succeeds.
 - Assert that the OIDC callback was called with the appropriate inputs, including the timeout parameter if possible.
 - Close the client.
 
 **2.2 OIDC Callback Returns Null**
 
-- Create a `MongoClient` configured with an OIDC callback that returns `null`.
+- Create an OIDC configured client with an OIDC callback that returns `null`.
 - Perform a `find` operation that fails.
 - Close the client.
 
 **2.3 OIDC Callback Returns Missing Data**
 
-- Create a `MongoClient` configured with an OIDC callback that returns data not conforming to the `OIDCCredential` with
+- Create an OIDC configured client with an OIDC callback that returns data not conforming to the `OIDCCredential` with
   missing fields.
 - Perform a `find` operation that fails.
 - Close the client.
 
 **2.4 Invalid Client Configuration with Callback**
 
-- Create a `MongoClient` configured with an OIDC callback and auth mechanism property `ENVIRONMENT:test`.
+- Create an OIDC configured client with an OIDC callback and auth mechanism property `ENVIRONMENT:test`.
 - Assert it returns a client configuration error.
 
 ### (3) Authentication Failure
 
 **3.1 Authentication failure with cached tokens fetch a new token and retry auth**
 
-- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic.
+- Create an OIDC configured client.
 - Poison the *Client Cache* with an invalid access token.
 - Perform a `find` operation that succeeds.
 - Assert that the callback was called 1 time.
 - Close the client.
 
 **3.2 Authentication failures without cached tokens return an error**
 
-- Create a `MongoClient` configured with an OIDC callback that always returns invalid access tokens.
+- Create an OIDC configured client with an OIDC callback that always returns invalid access tokens.
 - Perform a `find` operation that fails.
 - Assert that the callback was called 1 time.
 - Close the client.
 
 ### (4) Reauthentication
 
-- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic.
+- Create an OIDC configured client.
 - Set a fail point for `find` commands of the form:
 
 ```javascript
@@ -130,18 +119,18 @@ method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI`.
 ## (5) Azure Tests
 
 Drivers MUST only run the Azure tests when testing on an Azure VM. See instructions in
-[Drivers Evergreen Tools](https://github.com/mongodb-labs/drivers-evergreen-tools/tree/master/.evergreen/auth_oidc/azure#azure-oidc-testing)
+[Drivers Evergreen Tools](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/azure/README.md)
 for test setup.
 
 # 5.1 Azure With No Username
 
-- Create a `MongoClient` configured with `ENVIRONMENT:Azure` and a valid `TOKEN_RESOURCE` and no username.
+- Create an OIDC configured client with `ENVIRONMENT:azure` and a valid `TOKEN_RESOURCE` and no username.
 - Perform a `find` operation that succeeds.
 - Close the client.
 
 # 5.2 Azure with Bad Usernam
 
-- Create a `MongoClient` configured with `ENVIRONMENT:Azure` and a valid `TOKEN_RESOURCE` and a username of `"bad"`.
+- Create an OIDC configured client with `ENVIRONMENT:azure` and a valid `TOKEN_RESOURCE` and a username of `"bad"`.
 - Perform a `find` operation that fails.
 - Close the client.
 
@@ -152,71 +141,58 @@ ______________________________________________________________________
 Drivers that support the [Human Authentication Flow](../auth.md#human-authentication-flow) MUST implement all prose
 tests in this section. Unless otherwise noted, all `MongoClient` instances MUST be configured with `retryReads=false`.
 
-The human workflow tests MUST only be run when testing in the default environment described beflow.
+The human workflow tests MUST only be run when in `ENVIRONMENT:test`.
 
 > [!NOTE]
 > For test cases that create fail points, drivers MUST either use a unique `appName` or explicitly remove the fail point
 > after the test to prevent interaction between test cases.
 
 Drivers MUST be able to authenticate against a server configured with either one or two configured identity providers.
 
-Note that typically the preconfigured Atlas Dev clusters are used for testing, in Evergreen and locally. The URIs can be
-fetched from the `drivers/oidc` Secrets vault, see
-[vault instructions](https://wiki.corp.mongodb.com/display/DRIVERS/Using+AWS+Secrets+Manager+to+Store+Testing+Secrets).
-Use `OIDC_ATLAS_URI_SINGLE` for `MONGODB_URI_SINGLE` and `OIDC_ATLAS_URI_MULTI` for `MONGODB_URI_MULTI`. Currently the
-`OIDC_ATLAS_URI_MULTI` cluster does not work correctly with fail points, so all prose tests that use fail points SHOULD
-use `OIDC_ATLAS_URI_SINGLE`.
+Unless otherwise specified, use `MONGODB_URI_SINGLE` and the `test_user1` token in the `OIDC_TOKEN_DIR` as the
+"access_token", and a dummy "refresh_token" for all tests.
 
-If using local servers is preferred, using the
-[Local Testing](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/README.md#local-testing)
-method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI_SINGLE` and
-`mongodb://localhost:27018/?authMechanism=MONGODB-OIDC&directConnection=true&readPreference=secondaryPreferred` for
-`MONGODB_URI_MULTI` because the other server is a secondary on a replica set, on port `27018`.
-
-The default OIDC client used in the tests is configured with `MONGODB_URI_SINGLE` and a valid human callback handler
-that returns the `test_user1` local token in `OIDC_TOKEN_DIR` as the "access_token", and a dummy "refresh_token".
+When using an explicit username for the client, we use the token name and the domain name given by `OIDC_DOMAIN`, e.g.
+`test_user1@${OIDC_DOMAIN}`.
 
 ### (1) OIDC Human Callback Authentication
 
 Drivers MUST be able to authenticate using OIDC callback(s) when there is one principal configured.
 
 **1.1 Single Principal Implicit Username**
 
-- Create default OIDC client with `authMechanism=MONGODB-OIDC`.
+- Create an OIDC configured client.
 - Perform a `find` operation that succeeds.
 - Close the client.
 
 **1.2 Single Principal Explicit Username**
 
-- Create a client with `MONGODB_URI_SINGLE`, a username of `test_user1`, `authMechanism=MONGODB-OIDC`, and the OIDC
-  human callback.
+- Create an OIDC configured client with `MONGODB_URI_SINGLE` and a username of `test_user1@${OIDC_DOMAIN}`.
 - Perform a `find` operation that succeeds.
 - Close the client.
 
 **1.3 Multiple Principal User 1**
 
-- Create a client with `MONGODB_URI_MULTI`, a username of `test_user1`, `authMechanism=MONGODB-OIDC`, and the OIDC human
-  callback.
+- Create an OIDC configured client with `MONGODB_URI_MULTI` and username of `test_user1@${OIDC_DOMAIN}`.
 - Perform a `find` operation that succeeds.
 - Close the client.
 
 **1.4 Multiple Principal User 2**
 
-- Create a human callback that reads in the generated `test_user2` token file.
-- Create a client with `MONGODB_URI_MULTI`, a username of `test_user2`, `authMechanism=MONGODB-OIDC`, and the OIDC human
-  callback.
+- Create an OIDC configured client with `MONGODB_URI_MULTI` and username of `test_user2@${OIDC_DOMAIN}`. that reads the
+  `test_user2` token file.
 - Perform a `find` operation that succeeds.
 - Close the client.
 
 **1.5 Multiple Principal No User**
 
-- Create a client with `MONGODB_URI_MULTI`, no username, `authMechanism=MONGODB-OIDC`, and the OIDC human callback.
+- Create an OIDC configured client with `MONGODB_URI_MULTI` and no username.
 - Assert that a `find` operation fails.
 - Close the client.
 
 **1.6 Allowed Hosts Blocked**
 
-- Create a default OIDC client, with an `ALLOWED_HOSTS` that is an empty list.
+- Create an OIDC configured client with an `ALLOWED_HOSTS` that is an empty list.
 - Assert that a `find` operation fails with a client-side error.
 - Close the client.
 - Create a client that uses the URL `mongodb://localhost/?authMechanism=MONGODB-OIDC&ignored=example.com`, a human
@@ -228,23 +204,23 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 
 **2.1 Valid Callback Inputs**
 
-- Create a `MongoClient` with a human callback that validates its inputs and returns a valid access token.
+- Create an OIDC configured client with a human callback that validates its inputs and returns a valid access token.
 - Perform a `find` operation that succeeds. Verify that the human callback was called with the appropriate inputs,
   including the timeout parameter if possible.
 - Close the client.
 
 **2.3 Human Callback Returns Missing Data**
 
-- Create a `MongoClient` with a human callback that returns data not conforming to the `OIDCCredential` with missing
-  fields.
+- Create an OIDC configured client with a human callback that returns data not conforming to the `OIDCCredential` with
+  missing fields.
 - Perform a `find` operation that fails.
 - Close the client.
 
 ### (3) Speculative Authentication
 
 **3.1 Uses speculative authentication if there is a cached token**
 
-- Create a `MongoClient` with a human callback that returns a valid token.
+- Create an OIDC configured client with a human callback that returns a valid token.
 - Set a fail point for `find` commands of the form:
 
 ```javascript
@@ -283,7 +259,7 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 
 **3.2 Does not use speculative authentication if there is no cached token**
 
-- Create a `MongoClient` with a human callback that returns a valid token.
+- Create an OIDC configured client with a human callback that returns a valid token.
 - Set a fail point for `saslStart` commands of the form:
 
 ```javascript
@@ -306,7 +282,7 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 
 **4.1 Succeeds**
 
-- Create a default OIDC client and add an event listener. The following assumes that the driver does not emit
+- Create an OIDC configured client and add an event listener. The following assumes that the driver does not emit
   `saslStart` or `saslContinue` events. If the driver does emit those events, ignore/filter them for the purposes of
   this test.
 - Perform a `find` operation that succeeds.
@@ -339,7 +315,7 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 
 **4.2 Succeeds no refresh**
 
-- Create a default OIDC client with a human callback that does not return a refresh token.
+- Create an OIDC configured client with a human callback that does not return a 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:
@@ -365,7 +341,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 an OIDC configured client.
 - 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:
@@ -391,7 +367,7 @@ Drivers MUST be able to authenticate using OIDC callback(s) when there is one pr
 
 **4.4 Fails**
 
-- Create a default OIDC client.
+- Create an OIDC configured client.
 - Perform a find operation that succeeds (to force a speculative auth).
 - Assert that the human callback has been called once.
 - Force a reauthenication using a failCommand of the form: