From 37dd05585538bfbbd8782a6a6e13d9742edfe0c3 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Tue, 9 Sep 2025 13:33:02 -0400 Subject: [PATCH 01/15] DRIVERS-3207: Custom AWS credential providers execute first --- source/auth/auth.md | 10 +++++++--- source/auth/tests/mongodb-aws.md | 20 +++++++++++--------- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/source/auth/auth.md b/source/auth/auth.md index 22ac4ba845..ee8a072b7c 100644 --- a/source/auth/auth.md +++ b/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. diff --git a/source/auth/tests/mongodb-aws.md b/source/auth/tests/mongodb-aws.md index e64335c3cc..9ad9340ca0 100644 --- a/source/auth/tests/mongodb-aws.md +++ b/source/auth/tests/mongodb-aws.md @@ -21,15 +21,17 @@ SecretAccessKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Token=AQoDYXdzEJr... ``` -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: + +Scenarios 1-6 from the previous section with a user provided `AWS_CREDENTIAL_PROVIDER` auth mechanism property. This +value MAY 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 in each test. 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. For test scenarios where the drivers tools scripts put the +credentials in the MONGODB_URI, drivers MAY extract the credentials from the URI and return the AWS credentials directly +from the custom provider instead of using the AWS SDK default provider. ## Regular credentials From e5534c5fe4bb04db97939ba57e9df89214ed9db2 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 10 Sep 2025 17:11:19 -0400 Subject: [PATCH 02/15] chore: update auth changelog --- source/auth/auth.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/auth/auth.md b/source/auth/auth.md index ee8a072b7c..df7625c35f 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -2161,6 +2161,8 @@ practice to avoid this. (See ## Changelog +- 2025-09-10: Update precedence of MONGODB-AWS credential fetching behaviour. + - 2025-01-29: Add support for custom AWS credential providers. - 2024-10-02: Add Kubernetes built-in OIDC provider integration. From 0afb4e1e3de1a0b13ed1c190e4c7281205f05195 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Thu, 11 Sep 2025 08:34:06 -0400 Subject: [PATCH 03/15] chore prose test --- source/client-side-encryption/tests/README.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/source/client-side-encryption/tests/README.md b/source/client-side-encryption/tests/README.md index 9c0fa81656..5bbf4951af 100644 --- a/source/client-side-encryption/tests/README.md +++ b/source/client-side-encryption/tests/README.md @@ -3788,6 +3788,56 @@ class AutoEncryptionOpts { Assert that an error is thrown. +#### Case 4: ClientEncryption with `credentialProviders` and valid environment variables. + +Ensure a valid `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY` are present in the environment. + +Create a MongoClient named `setupClient`. + +Create a [ClientEncryption](../client-side-encryption.md#clientencryption) object with the following options: + +```typescript +class ClientEncryptionOpts { + keyVaultClient: , + keyVaultNamespace: "keyvault.datakeys", + kmsProviders: { "aws": {} }, + credentialProviders: { "aws": } +} +``` + +Use the client encryption to create a datakey using the "aws" KMS provider. This should successfully load and use the +AWS credentials that were provided by the secrets manager for the remote provider. Assert the datakey was created and +that the custom credential provider was called at least once. + +An example of this in Node.js: + +```typescript +import { ClientEncryption, MongoClient } from 'mongodb'; + +let calledCount = 0; +const masterKey = { + region: '', + key: '' +}; +const keyVaultClient = new MongoClient(process.env.MONGODB_URI); +const options = { + keyVaultNamespace: 'keyvault.datakeys', + kmsProviders: { aws: {} }, + credentialProviders: { + aws: async () => { + calledCount++; + return { + accessKeyId: process.env.FLE_AWS_KEY, + secretAccessKey: process.env.FLE_AWS_SECRET + }; + } + } +}; +const clientEncryption = new ClientEncryption(keyVaultClient, options); +const dk = await clientEncryption.createDataKey('aws', { masterKey }); +expect(dk).to.be.a(Binary); +expect(calledCount).to.be.greaterThan(0); +``` ### 27. Text Explicit Encryption The Text Explicit Encryption tests utilize Queryable Encryption (QE) range protocol V2 and require MongoDB server 8.2.0+ From d9de2c0b1693406dedd2c209d3076e2ca82ea51e Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Thu, 11 Sep 2025 09:29:12 -0400 Subject: [PATCH 04/15] chore: custom provider comments --- source/auth/auth.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source/auth/auth.md b/source/auth/auth.md index df7625c35f..81f1fed154 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -962,6 +962,7 @@ Examples are provided below. - AWS_CREDENTIAL_PROVIDER Drivers MAY allow the user to specify a custom credential provider object or function. + See [Custom Credential Providers](https://github.com/mongodb/specifications/blob/master/source/auth/auth.md#custom-credential-providers) #### Obtaining Credentials From 68fd633ce482821a6af7ca292b73f952d9d95897 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Fri, 12 Sep 2025 09:18:55 -0400 Subject: [PATCH 05/15] chore: comments --- source/auth/auth.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/auth/auth.md b/source/auth/auth.md index 81f1fed154..575a352be7 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -1010,8 +1010,8 @@ Drivers MAY expose API for default providers for the following scenarios when ap The order in which Drivers MUST search for credentials is: -1. A custom AWS credential provider if the driver supports it. -2. The URI +1. The URI +2. A custom AWS credential provider if the driver supports it. 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. From 94c7a1f5689847aec29c8989a6a7c797a06e6de5 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Fri, 12 Sep 2025 11:19:18 -0400 Subject: [PATCH 06/15] fix: lint --- source/auth/auth.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/auth/auth.md b/source/auth/auth.md index 575a352be7..3d9b610120 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -961,8 +961,8 @@ Examples are provided below. - AWS_CREDENTIAL_PROVIDER - Drivers MAY allow the user to specify a custom credential provider object or function. - See [Custom Credential Providers](https://github.com/mongodb/specifications/blob/master/source/auth/auth.md#custom-credential-providers) + Drivers MAY allow the user to specify a custom credential provider object or function. See + [Custom Credential Providers](https://github.com/mongodb/specifications/blob/master/source/auth/auth.md#custom-credential-providers) #### Obtaining Credentials From 1859b77e7cc6623b96deb15f437e1ecf463095a9 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Fri, 12 Sep 2025 11:28:31 -0400 Subject: [PATCH 07/15] fix: lint --- source/client-side-encryption/tests/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/source/client-side-encryption/tests/README.md b/source/client-side-encryption/tests/README.md index 5bbf4951af..1565f91219 100644 --- a/source/client-side-encryption/tests/README.md +++ b/source/client-side-encryption/tests/README.md @@ -3838,6 +3838,7 @@ const dk = await clientEncryption.createDataKey('aws', { masterKey }); expect(dk).to.be.a(Binary); expect(calledCount).to.be.greaterThan(0); ``` + ### 27. Text Explicit Encryption The Text Explicit Encryption tests utilize Queryable Encryption (QE) range protocol V2 and require MongoDB server 8.2.0+ From 5ea963f73cd75974dfc24eaa65d876002005aab7 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Tue, 16 Sep 2025 12:44:34 +0200 Subject: [PATCH 08/15] chore: relative link --- source/auth/auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/auth/auth.md b/source/auth/auth.md index 3d9b610120..ccc546648f 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -962,7 +962,7 @@ Examples are provided below. - AWS_CREDENTIAL_PROVIDER Drivers MAY allow the user to specify a custom credential provider object or function. See - [Custom Credential Providers](https://github.com/mongodb/specifications/blob/master/source/auth/auth.md#custom-credential-providers) + [Custom Credential Providers](#custom-credential-providers) #### Obtaining Credentials From ce60c553f6bd1b3ea50658d602a338ba21858fe9 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 17 Sep 2025 12:28:40 +0200 Subject: [PATCH 09/15] chore: update wording --- source/auth/auth.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/auth/auth.md b/source/auth/auth.md index ccc546648f..d453940330 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -961,8 +961,9 @@ Examples are provided below. - AWS_CREDENTIAL_PROVIDER - Drivers MAY allow the user to specify a custom credential provider object or function. See - [Custom Credential Providers](#custom-credential-providers) + An AWS [Custom Credential Provider](#custom-credential-providers) that returns AWS credentials. Drivers MAY + allow the user to specify an object or function, depending on what is idiomatic for the driver. This property + MUST follow the same API as the driver language's AWS SDK credential provider. #### Obtaining Credentials From 5e6c5f8e2085195fdb5ec4ec33639826e2f13558 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 17 Sep 2025 12:30:55 +0200 Subject: [PATCH 10/15] chore: lint --- source/auth/auth.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/auth/auth.md b/source/auth/auth.md index d453940330..4e20c04922 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -961,9 +961,9 @@ Examples are provided below. - AWS_CREDENTIAL_PROVIDER - An AWS [Custom Credential Provider](#custom-credential-providers) that returns AWS credentials. Drivers MAY - allow the user to specify an object or function, depending on what is idiomatic for the driver. This property - MUST follow the same API as the driver language's AWS SDK credential provider. + An AWS [Custom Credential Provider](#custom-credential-providers) that returns AWS credentials. Drivers MAY allow + the user to specify an object or function, depending on what is idiomatic for the driver. This property MUST + follow the same API as the driver language's AWS SDK credential provider. #### Obtaining Credentials From 536b90b269a83332077f357fc1d59d21bab54b51 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 17 Sep 2025 12:45:03 +0200 Subject: [PATCH 11/15] fix: env var naming --- source/client-side-encryption/tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/client-side-encryption/tests/README.md b/source/client-side-encryption/tests/README.md index 1565f91219..ce5370c210 100644 --- a/source/client-side-encryption/tests/README.md +++ b/source/client-side-encryption/tests/README.md @@ -3790,7 +3790,7 @@ Assert that an error is thrown. #### Case 4: ClientEncryption with `credentialProviders` and valid environment variables. -Ensure a valid `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY` are present in the environment. +Ensure a valid `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are present in the environment. Create a MongoClient named `setupClient`. From 922e3b189c3e722e3474fda43ea7b977a52969c8 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 17 Sep 2025 20:28:11 +0200 Subject: [PATCH 12/15] Update source/auth/tests/mongodb-aws.md Co-authored-by: Kevin Albertson --- source/auth/tests/mongodb-aws.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/auth/tests/mongodb-aws.md b/source/auth/tests/mongodb-aws.md index 9ad9340ca0..ec5c66ccc7 100644 --- a/source/auth/tests/mongodb-aws.md +++ b/source/auth/tests/mongodb-aws.md @@ -26,7 +26,7 @@ Token=AQoDYXdzEJr... If the driver supports custom AWS credential providers, the driver MUST test the following: Scenarios 1-6 from the previous section with a user provided `AWS_CREDENTIAL_PROVIDER` auth mechanism property. This -value MAY be the default credential provider from the AWS SDK. If the default provider does not cover all scenarios +credentials MAY be obtained from 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 in each test. 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. For test scenarios where the drivers tools scripts put the From ed72b6355dadb055bc78c1815d8a20f71b4f4769 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 17 Sep 2025 20:37:03 +0200 Subject: [PATCH 13/15] chore: comments --- source/auth/tests/mongodb-aws.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/source/auth/tests/mongodb-aws.md b/source/auth/tests/mongodb-aws.md index ec5c66ccc7..1365c3ad90 100644 --- a/source/auth/tests/mongodb-aws.md +++ b/source/auth/tests/mongodb-aws.md @@ -2,7 +2,7 @@ Drivers MUST test the following scenarios: -1. `Regular Credentials`: Auth via an `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY` pair +1. `Regular Credentials`: Auth via an `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` pair 2. `EC2 Credentials`: Auth from an EC2 instance via temporary credentials assigned to the machine 3. `ECS Credentials`: Auth from an ECS instance via temporary credentials assigned to the task 4. `Assume Role`: Auth via temporary credentials obtained from an STS AssumeRole request @@ -25,6 +25,8 @@ Token=AQoDYXdzEJr... If the driver supports custom AWS credential providers, the driver MUST test the following: +### 1. Custom Credential Provider Authenticates + Scenarios 1-6 from the previous section with a user provided `AWS_CREDENTIAL_PROVIDER` auth mechanism property. This credentials MAY be obtained from 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 @@ -33,6 +35,26 @@ provider and asserts that it was called at least once. For test scenarios where credentials in the MONGODB_URI, drivers MAY extract the credentials from the URI and return the AWS credentials directly from the custom provider instead of using the AWS SDK default provider. +### 2. Custom Credential Provider Authentication Precedence + +#### Case 1: Credentials in URI Take Precedence + +Create a `MongoClient` configured with AWS auth and credentials in the URI. Example: `mongodb://:@localhost:27017/?authMechanism=MONGODB-AWS` + +Configure a custom credential provider to pass valid AWS credentials. The provider must track if it was called. + +Expect authentication to succeed and the custom credential provider was *not* called. + +#### Case 2: Custom Provider Takes Precedence Over Environment Variables + +Run this test in an environment with AWS credentials configured as environment variables (e.g. `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`) + +Create a `MongoClient` configured to use AWS auth. Example: `mongodb://localhost:27017/?authMechanism=MONGODB-AWS`. + +Configure a custom credential provider to pass valid AWS credentials. The provider must track if it was called. + +Expect authentication to succeed and the custom credential provider was called. + ## Regular credentials Drivers MUST be able to authenticate by providing a valid access key id and secret access key pair as the username and From 18eb8e01d712b2e0e5a6e9d6bafecc234c3ec899 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 17 Sep 2025 20:41:36 +0200 Subject: [PATCH 14/15] fix: lint --- source/auth/tests/mongodb-aws.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/auth/tests/mongodb-aws.md b/source/auth/tests/mongodb-aws.md index 1365c3ad90..e61266f0b5 100644 --- a/source/auth/tests/mongodb-aws.md +++ b/source/auth/tests/mongodb-aws.md @@ -39,7 +39,8 @@ from the custom provider instead of using the AWS SDK default provider. #### Case 1: Credentials in URI Take Precedence -Create a `MongoClient` configured with AWS auth and credentials in the URI. Example: `mongodb://:@localhost:27017/?authMechanism=MONGODB-AWS` +Create a `MongoClient` configured with AWS auth and credentials in the URI. Example: +`mongodb://:@localhost:27017/?authMechanism=MONGODB-AWS` Configure a custom credential provider to pass valid AWS credentials. The provider must track if it was called. @@ -47,9 +48,10 @@ Expect authentication to succeed and the custom credential provider was *not* ca #### Case 2: Custom Provider Takes Precedence Over Environment Variables -Run this test in an environment with AWS credentials configured as environment variables (e.g. `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`) +Run this test in an environment with AWS credentials configured as environment variables (e.g. `AWS_ACCESS_KEY_ID`, +`AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`) -Create a `MongoClient` configured to use AWS auth. Example: `mongodb://localhost:27017/?authMechanism=MONGODB-AWS`. +Create a `MongoClient` configured to use AWS auth. Example: `mongodb://localhost:27017/?authMechanism=MONGODB-AWS`. Configure a custom credential provider to pass valid AWS credentials. The provider must track if it was called. From ec586a631d53974db5ca046234c4bdbcd92e3727 Mon Sep 17 00:00:00 2001 From: Durran Jordan Date: Wed, 17 Sep 2025 20:52:32 +0200 Subject: [PATCH 15/15] fix: lint --- source/auth/tests/mongodb-aws.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/auth/tests/mongodb-aws.md b/source/auth/tests/mongodb-aws.md index e61266f0b5..d828f7a8fe 100644 --- a/source/auth/tests/mongodb-aws.md +++ b/source/auth/tests/mongodb-aws.md @@ -28,12 +28,12 @@ If the driver supports custom AWS credential providers, the driver MUST test the ### 1. Custom Credential Provider Authenticates Scenarios 1-6 from the previous section with a user provided `AWS_CREDENTIAL_PROVIDER` auth mechanism property. This -credentials MAY be obtained from 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 in each test. 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. For test scenarios where the drivers tools scripts put the -credentials in the MONGODB_URI, drivers MAY extract the credentials from the URI and return the AWS credentials directly -from the custom provider instead of using the AWS SDK default provider. +credentials MAY be obtained from 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 in each test. 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. For test scenarios where the drivers tools scripts +put the credentials in the MONGODB_URI, drivers MAY extract the credentials from the URI and return the AWS credentials +directly from the custom provider instead of using the AWS SDK default provider. ### 2. Custom Credential Provider Authentication Precedence