DRIVERS-2333 Cache AWS Credentials Where Possible (#1281)

Author: blink1073

source/auth/auth.rst

@@ -1098,6 +1098,29 @@ From the JSON response drivers
 MUST obtain the ``access_key``, ``secret_key`` and ``security_token`` which will be used during the `Signature Version 4 Signing Process 
 <https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html?shortFooter=true>`_.
 
+Caching Credentials
+___________________
+Credentials fetched by the driver using AWS endpoints MUST be cached and reused
+to avoid hitting AWS rate limitations. AWS recommends using a suitable
+Software Development Kit (SDK) for your langauge. If that SDK supports
+credential fetch and automatic refresh/caching, then that mechanism can
+be used in lieu of manual caching.
+
+If using manual caching, the "Expiration" field MUST be stored
+and used to determine when to clear the cache. Credentials are considered
+valid if they are more than five minutes away from expiring; to the reduce the
+chance of expiration before they are validated by the server.
+
+If there are no current valid cached credentials, the driver MUST initiate a
+credential request. To avoid adding a bottleneck that would override the
+``maxConnecting`` setting, the driver MUST not place a lock on making a
+request. The cache MUST be written atomically.
+
+If AWS authentication fails for any reason, the cache MUST be cleared.
+
+.. note::
+    Five minutes was chosen based on the AWS documentation for `IAM roles for EC2 <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html>`_ : "We make new credentials available at least five minutes before the expiration of the old credentials". The intent is to have some buffer between when the driver fetches the credentials and when the server verifies them.
+
 -------------------------
 Connection String Options
 -------------------------
@@ -1334,6 +1357,7 @@ Q: Should drivers support accessing Amazon EC2 instance metadata in Amazon ECS?
 Changelog
 =========
 
+:2022-10-07: Require caching of AWS credentials fetched by the driver.
 :2022-10-05: Remove spec front matter and convert version history to changelog.
 :2022-09-07: Add support for AWS AssumeRoleWithWebIdentity.
 :2022-01-20: Require that timeouts be applied per the client-side operations timeout spec.

source/auth/tests/mongodb-aws.rst

@@ -10,6 +10,7 @@ There are 6 scenarios drivers MUST test:
 #. ``Assume Role``: Auth via temporary credentials obtained from an STS AssumeRole request
 #. ``Assume Role with Web Identity``: Auth via temporary credentials obtained from an STS AssumeRoleWithWebIdentity request
 #. ``AWS Lambda``: Auth via environment variables ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY``, and ``AWS_SESSION_TOKEN``.
+#. Caching of AWS credentials fetched by the driver.
 
 For brevity, this section gives the values ``<AccessKeyId>``, ``<SecretAccessKey>`` and ``<Token>`` in place of a valid access key ID, secret access key and session token (also known as a security token). Note that if these values are passed into the URI they MUST be URL encoded. Sample values are below.
 
@@ -115,3 +116,26 @@ Sample URIs both with and without optional session tokens set are shown below. D
   URI="mongodb://localhost/?authMechanism=MONGODB-AWS"
 
 .. note:: No username, password or session token is passed into the URI. Drivers MUST check the environment variables listed above for these values. If the session token is set Drivers MUST use it.
+
+
+Cached Credentials
+==================
+
+Drivers MUST ensure that they are testing the ability to cache credentials.
+Drivers will need to be able to query and override the cached credentials to
+verify usage.  To determine whether to run the cache tests, the driver can
+check for the absence of the AWS_ACCESS_KEY_ID and of credentials in the URI.
+
+#. Clear the cache.
+#. Create a new client.
+#. Ensure that a ``find`` operation adds credentials to the cache.
+#. Override the cached credentials with an "Expiration" that is within one
+   minute of the current UTC time.
+#. Create a new client.
+#. Ensure that a ``find`` operation updates the credentials in the cache.
+#. Poison the cache with an invalid access key id.
+#. Create a new client.
+#. Ensure that a ``find`` operation results in an error.
+#. Ensure that the cache has been cleared.
+#. Ensure that a subsequent ``find`` operation succeeds.
+#. Ensure that the cache has been set.