DRIVERS-3207: Custom AWS credential providers execute first

Author: durran

source/auth/auth.md

@@ -959,6 +959,10 @@ Examples are provided below.
 
         Drivers MUST allow the user to specify an AWS session token for authentication with temporary credentials.
 
+    - AWS_CREDENTIAL_PROVIDER
+
+        Drivers MAY allow the user to specify a custom credential provider object or function.
+
 #### Obtaining Credentials
 
 Drivers will need AWS IAM credentials (an access key, a secret access key and optionally a session token) to complete
@@ -1005,9 +1009,9 @@ Drivers MAY expose API for default providers for the following scenarios when ap
 
 The order in which Drivers MUST search for credentials is:
 
-1. The URI
-2. Environment variables
-3. A custom AWS credential provider if the driver supports it.
+1. A custom AWS credential provider if the driver supports it.
+2. The URI
+3. Environment variables
 4. Using `AssumeRoleWithWebIdentity` if `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN` are set.
 5. The ECS endpoint if `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set. Otherwise, the EC2 endpoint.
 

source/auth/tests/mongodb-aws.md

@@ -21,15 +21,21 @@ SecretAccessKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
 Token=AQoDYXdzEJr...<remainder of security token>
 ```
 
-If the driver supports user provided custom AWS credential providers, then the driver MUST also test the above scenarios
-2-6 with a user provided `AWS_CREDENTIAL_PROVIDER` auth mechanism property. This value MUST be the default credential
-provider from the AWS SDK. If the default provider does not cover all scenarios above, those not covered MAY be skipped.
-In these tests the driver MUST also assert that the user provided credential provider was called at least once in each
-test.
-
-If the driver supports a custom AWS credential provider, it MUST verify the custom provider was used when testing. This
-may be via a custom function or object that wraps the calls to the custom provider and asserts that it was called at
-least once.
+## Testing custom credential providers
+
+If the driver supports custom AWS credential providers, the driver MUST test the following:
+
+Scenario 1 from the previous section where the `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY` pair are provided as client
+options, but are incorrect, and a custom `AWS_CREDENTIAL_PROVIDER` that returns the correct values for these two
+properties.
+
+Scenarios 2-6 from the previous section with a user provided `AWS_CREDENTIAL_PROVIDER` auth mechanism property. This
+value MUST be the default credential provider from the AWS SDK. If the default provider does not cover all scenarios
+above, those not covered MAY be skipped. In these tests the driver MUST also assert that the user provided credential
+provider was called at least once in each test.
+
+The driver MUST verify the custom provider was used when testing. This may be via a custom function or object that wraps
+the calls to the custom provider and asserts that it was called at least once.
 
 ## Regular credentials