diff --git a/source/code-snippets/authentication/aws-custom-credentials.js b/source/code-snippets/authentication/aws-custom-credentials.js new file mode 100644 index 000000000..7b4e012fb --- /dev/null +++ b/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('?authMechanism=MONGODB-AWS', { + authMechanismProperties: { + AWS_CREDENTIAL_PROVIDER: fromNodeProviderChain() + } + }); + // end-custom-credentials +} + +{ + // start-custom-credentials-function + const { MongoClient } = require('mongodb'); + + const client = new MongoClient('?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 +} \ No newline at end of file diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt index d647633ff..168c7171e 100644 --- a/source/security/authentication/aws-iam.txt +++ b/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 `__. + +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 -----------------