DOCSP-46858: Add custom AWS credential documentation (#1160)

Author: mcmorisi

source/code-snippets/authentication/aws-custom-credentials.js

@@ -0,0 +1,29 @@
+{
+    // start-custom-credentials
+    const { MongoClient } = require('mongodb');
+    const { fromNodeProviderChain } = require('@aws-sdk/credential-providers');
+
+    const client = new MongoClient('<cluster_url>?authMechanism=MONGODB-AWS', {
+        authMechanismProperties: {
+            AWS_CREDENTIAL_PROVIDER: fromNodeProviderChain()
+        }
+    });
+    // end-custom-credentials
+}
+
+{
+    // start-custom-credentials-function
+    const { MongoClient } = require('mongodb');
+
+    const client = new MongoClient('<cluster_url>?authMechanism=MONGODB-AWS', {
+        authMechanismProperties: {
+            AWS_CREDENTIAL_PROVIDER: async () => {
+                return {
+                    accessKeyId: process.env.ACCESS_KEY_ID,
+                    secretAccessKey: process.env.SECRET_ACCESS_KEY
+                }
+            }
+        }
+    });
+    // end-custom-credentials-function
+}

source/security/authentication/aws-iam.txt

@@ -153,23 +153,38 @@ The driver checks for your credentials in the following sources in order:
       .. literalinclude:: /code-snippets/authentication/aws-env-variable.js
          :language: javascript
 
-.. important:: Retrieval of AWS Credentials
-   
-   Starting in MongoDB version 4.11, when you install the optional
-   ``aws-sdk/credential-providers`` dependency, the driver uses the AWS SDK
-   to retrieve credentials from the environment. As a result, if you
-   have a shared AWS credentials file or config file, the driver will
-   use those credentials by default.
-   
-   You can override this behavior by performing one of the following
-   actions:
-   
-   - Set ``AWS_SHARED_CREDENTIALS_FILE`` variable in your shell to point
-     to your credentials file.
-   - Set the equivalent environment variable in your application to point
-     to your credentials file.
-   - Create an AWS profile for your MongoDB credentials and set the
-     ``AWS_PROFILE`` environment variable to that profile name.
+Specifying AWS Credentials
+--------------------------
+
+When you install the optional ``aws-sdk/credential-providers`` dependency, the driver
+retrieves credentials in a priority order defined by the AWS SDK. If you have a shared AWS
+credentials file or config file, the driver uses those credentials by default.
+
+.. tip::
+
+   To learn more about how the ``aws-sdk/credential-providers`` dependency retrieves
+   credentials, see the `AWS SDK documentation <https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromnodeproviderchain>`__.
+
+To manually specify the AWS credentials to retrieve, you can set the ``AWS_CREDENTIAL_PROVIDER``
+property to a defined credential provider from the AWS SDK. The following example passes a provider chain
+from the AWS SDK to the AWS authentication mechanism:
+
+.. literalinclude:: /code-snippets/authentication/aws-custom-credentials.js
+   :language: javascript
+   :start-after: // start-custom-credentials
+   :end-before: // end-custom-credentials
+   :dedent:
+
+To use a custom provider, you can pass any asynchronous function that returns your credentials
+to the ``AWS_CREDENTIAL_PROVIDER`` authentication mechanism property. The following example shows how to pass
+a custom provider function that fetches credentials from environment variables to the
+AWS authentication mechanism:
+
+.. literalinclude:: /code-snippets/authentication/aws-custom-credentials.js
+   :language: javascript
+   :start-after: // start-custom-credentials-function
+   :end-before: // end-custom-credentials-function
+   :dedent:
 
 API Documentation
 -----------------