From 98d031b3fd47831c98ea056e047c350192742a53 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 6 Jun 2025 11:09:46 -0400 Subject: [PATCH 1/9] DOCSP-46858: Add custom AWS credential documentation --- .../authentication/aws-custom-credentials.js | 25 +++++++++++ source/security/authentication/aws-iam.txt | 42 +++++++++++-------- 2 files changed, 50 insertions(+), 17 deletions(-) create mode 100644 source/code-snippets/authentication/aws-custom-credentials.js 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..f80b1e040 --- /dev/null +++ b/source/code-snippets/authentication/aws-custom-credentials.js @@ -0,0 +1,25 @@ +// 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..ab2194828 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -153,23 +153,31 @@ 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. +Retrieving AWS Credentials +-------------------------- + +When you install the optional ``aws-sdk/credential-providers`` dependency, the driver +uses the AWS SDK to retrieve credentials from the environment. If you have a shared AWS +credentials file or config file, the driver uses those credentials by default. + +To manually specify the AWS credentials to retrieve, you can use the ``AWS_CREDENTIAL_PROVIDER`` +property to specify the credential provider. 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 + +TO use a custom provider, you can pass any async function that returns your credentials +to the ``AWS_CREDENTIAL_PROVIDER`` 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 API Documentation ----------------- From cf46f7b2996e4a53f2e2a98644e785d04b190466 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 6 Jun 2025 11:16:03 -0400 Subject: [PATCH 2/9] Fixes --- source/security/authentication/aws-iam.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt index ab2194828..b30852d80 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -153,7 +153,7 @@ The driver checks for your credentials in the following sources in order: .. literalinclude:: /code-snippets/authentication/aws-env-variable.js :language: javascript -Retrieving AWS Credentials +Specifying AWS Credentials -------------------------- When you install the optional ``aws-sdk/credential-providers`` dependency, the driver @@ -169,7 +169,7 @@ from the AWS SDK to the AWS authentication mechanism: :start-after: // start-custom-credentials :end-before: // end-custom-credentials -TO use a custom provider, you can pass any async function that returns your credentials +To use a custom provider, you can pass any asynchronous function that returns your credentials to the ``AWS_CREDENTIAL_PROVIDER`` property. The following example shows how to pass a custom provider function that fetches credentials from environment variables to the AWS authentication mechanism: From c546f24576ecbccd8831c6c8eb95bd4823f46710 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 6 Jun 2025 11:18:20 -0400 Subject: [PATCH 3/9] Fix --- .../authentication/aws-custom-credentials.js | 42 ++++++++++--------- source/security/authentication/aws-iam.txt | 4 +- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/source/code-snippets/authentication/aws-custom-credentials.js b/source/code-snippets/authentication/aws-custom-credentials.js index f80b1e040..6f2bb0449 100644 --- a/source/code-snippets/authentication/aws-custom-credentials.js +++ b/source/code-snippets/authentication/aws-custom-credentials.js @@ -1,25 +1,29 @@ -// start-custom-credentials -const { MongoClient } = require('mongodb'); -const { fromNodeProviderChain } = require('@aws-sdk/credential-providers'); +{ + // 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 + const client = new MongoClient('?authMechanism=MONGODB-AWS', { + authMechanismProperties: { + AWS_CREDENTIAL_PROVIDER: fromNodeProviderChain() + } + }); + // end-custom-credentials +} +{ // start-custom-credentials-function -const { MongoClient } = require('mongodb'); + 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 + 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 + }); + // 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 b30852d80..29e68b6a1 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -167,7 +167,8 @@ 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 + :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`` property. The following example shows how to pass @@ -178,6 +179,7 @@ AWS authentication mechanism: :language: javascript :start-after: // start-custom-credentials-function :end-before: // end-custom-credentials-function + :dedent: API Documentation ----------------- From 57c49c00c68641429c694dd12890c99714175758 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 6 Jun 2025 11:18:40 -0400 Subject: [PATCH 4/9] Fix --- source/code-snippets/authentication/aws-custom-credentials.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/code-snippets/authentication/aws-custom-credentials.js b/source/code-snippets/authentication/aws-custom-credentials.js index 6f2bb0449..7b4e012fb 100644 --- a/source/code-snippets/authentication/aws-custom-credentials.js +++ b/source/code-snippets/authentication/aws-custom-credentials.js @@ -12,7 +12,7 @@ } { -// start-custom-credentials-function + // start-custom-credentials-function const { MongoClient } = require('mongodb'); const client = new MongoClient('?authMechanism=MONGODB-AWS', { From a9413ad3046eef696b6d419e128325aecccfa7d7 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 6 Jun 2025 12:33:30 -0400 Subject: [PATCH 5/9] NR feedback --- source/security/authentication/aws-iam.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt index 29e68b6a1..3e2565f49 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -160,8 +160,8 @@ When you install the optional ``aws-sdk/credential-providers`` dependency, the d uses the AWS SDK to retrieve credentials from the environment. If you have a shared AWS credentials file or config file, the driver uses those credentials by default. -To manually specify the AWS credentials to retrieve, you can use the ``AWS_CREDENTIAL_PROVIDER`` -property to specify the credential provider. The following example passes a provider chain +To manually specify the AWS credentials to retrieve, you can set the ``AWS_CREDENTIAL_PROVIDER`` +property to the credential provider. The following example passes a provider chain from the AWS SDK to the AWS authentication mechanism: .. literalinclude:: /code-snippets/authentication/aws-custom-credentials.js From 295211b38301e405fa7ee2fa0cee3319828e4964 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 10 Jun 2025 14:46:31 -0400 Subject: [PATCH 6/9] Durran feedback --- source/security/authentication/aws-iam.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt index 3e2565f49..0e1c5bbbd 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -157,11 +157,11 @@ Specifying AWS Credentials -------------------------- When you install the optional ``aws-sdk/credential-providers`` dependency, the driver -uses the AWS SDK to retrieve credentials from the environment. If you have a shared AWS +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. To manually specify the AWS credentials to retrieve, you can set the ``AWS_CREDENTIAL_PROVIDER`` -property to the credential provider. The following example passes a provider chain +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 @@ -171,7 +171,7 @@ from the AWS SDK to the AWS authentication mechanism: :dedent: To use a custom provider, you can pass any asynchronous function that returns your credentials -to the ``AWS_CREDENTIAL_PROVIDER`` property. The following example shows how to pass +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: @@ -181,6 +181,9 @@ AWS authentication mechanism: :end-before: // end-custom-credentials-function :dedent: +To learn more about how the ``aws-sdk/credential-providers`` dependency retrieves +credentials, see the `AWS SDK documentation `__. + API Documentation ----------------- From cac2dae78cce3e1ad4c04ccef62067763c422197 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 10 Jun 2025 14:52:58 -0400 Subject: [PATCH 7/9] Fix --- source/security/authentication/aws-iam.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt index 0e1c5bbbd..168c7171e 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -160,6 +160,11 @@ When you install the optional ``aws-sdk/credential-providers`` dependency, the d 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: @@ -181,9 +186,6 @@ AWS authentication mechanism: :end-before: // end-custom-credentials-function :dedent: -To learn more about how the ``aws-sdk/credential-providers`` dependency retrieves -credentials, see the `AWS SDK documentation `__. - API Documentation ----------------- From 9332cb47bc87a8f7ef238677ecb5601c1581499a Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 10 Jun 2025 14:57:07 -0400 Subject: [PATCH 8/9] Fix --- source/security/authentication/aws-iam.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt index 168c7171e..94f03f4f8 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -163,7 +163,7 @@ 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 `__. + 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 90ddd610cb3861be2cb9f85147dc9eaf8614fe1e Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 10 Jun 2025 15:11:58 -0400 Subject: [PATCH 9/9] Reverting --- source/security/authentication/aws-iam.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/security/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt index 94f03f4f8..168c7171e 100644 --- a/source/security/authentication/aws-iam.txt +++ b/source/security/authentication/aws-iam.txt @@ -163,7 +163,7 @@ 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 `__. + 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