Skip to content

DRIVERS-3131: No explicitly provided properties with MONGODB-AWS #1847

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Open

DRIVERS-3131: No explicitly provided properties with MONGODB-AWS #1847

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
30808eb
DRIVERS-3131: No URI credentials with MONGODB-AWS
durran Sep 30, 2025
8ed234a
fix: lint
durran Sep 30, 2025
51184d3
chore: add note on error cases
durran Sep 30, 2025
df19d50
fix: lint
durran Sep 30, 2025
8a8ecaf
chore: comments
durran Oct 1, 2025
6633b5a
chore: comments
durran Oct 1, 2025
aad1e8a
fix: lint
durran Oct 1, 2025
7714280
chore: comments
durran Oct 6, 2025
714e051
chore: comments
durran Oct 6, 2025
1780f54
test: fix tests
durran Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 14 additions & 34 deletions source/auth/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -955,10 +955,6 @@ Examples are provided below.
- mechanism_properties
- AWS_SESSION_TOKEN
Drivers MUST allow the user to specify an AWS session token for authentication with temporary credentials.
- AWS_CREDENTIAL_PROVIDER
An AWS [Custom Credential Provider](#custom-credential-providers) that returns AWS credentials. Drivers MAY allow
Expand All @@ -970,11 +966,10 @@ Examples are provided below.
Drivers will need AWS IAM credentials (an access key, a secret access key and optionally a session token) to complete
the steps in the
[Signature Version 4 Signing Process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html?shortFooter=true).
If a username and password are provided drivers MUST use these for the AWS IAM access key and AWS IAM secret key,
respectively. If, additionally, a session token is provided Drivers MUST use it as well. If a username is provided
without a password (or vice-versa) or if *only* a session token is provided Drivers MUST raise an error. In other words,
regardless of how Drivers obtain credentials the only valid combination of credentials is an access key ID and a secret
access key or an access key ID, a secret access key and a session token.
Regardless of how Drivers obtain credentials the only valid combination of credentials is an access key ID and a secret
access key or an access key ID, a secret access key and a session token. These values MUST be present in the environment
or be retrieved via the optional AWS SDK. If credentials are provided in the URI or client options, the driver MUST
raise an error.

AWS recommends using an SDK to "take care of some of the heavy lifting necessary in successfully making API calls,
including authentication, retry behavior, and more".
Expand Down Expand Up @@ -1011,11 +1006,10 @@ 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. 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.
1. A custom AWS credential provider if the driver supports it.
2. Environment variables
3. Using `AssumeRoleWithWebIdentity` if `AWS_WEB_IDENTITY_TOKEN_FILE` and `AWS_ROLE_ARN` are set.
4. The ECS endpoint if `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set. Otherwise, the EC2 endpoint.
> [!NOTE]
> See *Should drivers support accessing Amazon EC2 instance metadata in Amazon ECS* in [Q & A](#q-and-a)
Expand All @@ -1025,32 +1019,16 @@ The order in which Drivers MUST search for credentials is:
> description of `AssumeRole` below, which is distinct from `AssumeRoleWithWebIdentity` requests that are meant to be
> handled directly by the driver.
##### URI
An example URI for authentication with MONGODB-AWS using AWS IAM credentials passed through the URI is as follows:
```javascript
"mongodb://<access_key>:<secret_key>@mongodb.example.com/?authMechanism=MONGODB-AWS"
```
Users MAY have obtained temporary credentials through an
[AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) request. If so, then in addition
to a username and password, users MAY also provide an `AWS_SESSION_TOKEN` as a `mechanism_property`.
```javascript
"mongodb://<access_key>:<secret_key>@mongodb.example.com/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<security_token>"
```
##### Environment variables
AWS Lambda runtimes set several
[environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime)
during initialization. To support AWS Lambda runtimes Drivers MUST check a subset of these variables, i.e.,
`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN`, for the access key ID, secret access key and
session token, respectively if AWS credentials are not explicitly provided in the URI. The `AWS_SESSION_TOKEN` may or
may not be set. However, if `AWS_SESSION_TOKEN` is set Drivers MUST use its value as the session token. Drivers
implemented in programming languages that support altering environment variables MUST always read environment variables
dynamically during authorization, to handle the case where another part the application has refreshed the credentials.
session token, respectively. The `AWS_SESSION_TOKEN` may or may not be set. However, if `AWS_SESSION_TOKEN` is set
Drivers MUST use its value as the session token. Drivers implemented in programming languages that support altering
environment variables MUST always read environment variables dynamically during authorization, to handle the case where
another part the application has refreshed the credentials.
However, if environment variables are not present during initial authorization, credentials may be fetched from another
source and cached. Even if the environment variables are present in subsequent authorization attempts, the driver MUST
Expand Down Expand Up @@ -2165,6 +2143,8 @@ practice to avoid this. (See

## Changelog

- 2025-09-30: Remove support for explicitly specifying MONGODDB-AWS authentication properties.

- 2025-09-10: Update precedence of MONGODB-AWS credential fetching behaviour.

- 2025-01-29: Add support for custom AWS credential providers.
Expand Down
15 changes: 15 additions & 0 deletions source/auth/tests/legacy/connection-string.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 9 additions & 0 deletions source/auth/tests/legacy/connection-string.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,15 @@ tests:
mechanism: MONGODB-AWS
mechanism_properties:
AWS_SESSION_TOKEN: token!@#$%^&*()_+
- description: should throw an exception if username provided (MONGODB-AWS)
uri: mongodb://[email protected]/?authMechanism=MONGODB-AWS
valid: false
- description: should throw an exception if username and password provided (MONGODB-AWS)
uri: mongodb://user:[email protected]/?authMechanism=MONGODB-AWS
valid: false
- description: should throw an exception if AWS_SESSION_TOKEN provided (MONGODB-AWS)
uri: mongodb://localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:token
valid: false
- description: should recognise the mechanism with test environment (MONGODB-OIDC)
uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:test
valid: true
Expand Down
26 changes: 9 additions & 17 deletions source/auth/tests/mongodb-aws.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Drivers MUST test the following scenarios:

1. `Regular Credentials`: Auth via an `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` pair
1. `Regular Credentials`: Auth via an `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` pair *Removed*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't we still want to test this with env vars?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is now fixed.

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
Expand All @@ -12,8 +12,7 @@ Drivers MUST test the following scenarios:
7. 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.
key ID, secret access key and session token (also known as a security token). Sample values are below.

```text
AccessKeyId=AKIAI44QH8DHBEXAMPLE
Expand All @@ -37,14 +36,7 @@ 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://<AccessKeyId>:<SecretAccessKey>@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 1: Credentials in URI Take Precedence *Removed*

#### Case 2: Custom Provider Takes Precedence Over Environment Variables

Expand All @@ -59,11 +51,11 @@ 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
password, respectively, in the MongoDB URI. An example of a valid URI would be:
Drivers MUST be able to authenticate when a valid access key id and secret access key pair are present in the
environment. Drivers MUST provide the --nouri option to aws_tester.py in drivers-evergreen-tools for this test.

```text
mongodb://<AccessKeyId>:<SecretAccessKey>@localhost/?authMechanism=MONGODB-AWS
mongodb://localhost/?authMechanism=MONGODB-AWS
```

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also update the other prose tests that are no longer relevant in this file (strike-through, or replace the title with *Removed* per prose test guidelines)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the the prose tests are still valid and I updated the assume role test to note as well to pass --nouri

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe Case 1 above would fall into the category of "no longer relevant" after this set of changes, so I was suggesting the strike-through method. There is also a callout about URI encoding in L15-16 of this file that should probably be amended.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added the Removed label to the titles.

Copy link
Contributor

@dariakp dariakp Oct 6, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think those are the tests we want to remove. In addition, the guidelines for removing tests say to either remove the whole test and replace the title with "Removed" OR strikethrough the entire content - just adding a "removed" label and keeping everything else in place might be confusing.

## EC2 Credentials
Expand Down Expand Up @@ -95,11 +87,11 @@ mongodb://localhost/?authMechanism=MONGODB-AWS
## AssumeRole

Drivers MUST be able to authenticate using temporary credentials returned from an assume role request. These temporary
credentials consist of an access key ID, a secret access key, and a security token passed into the URI. A sample URI
would be:
credentials consist of an access key ID, a secret access key, and a security token present in the environment. Drivers
MUST provide the --nouri option to aws_tester.py in drivers-evergreen-tools for this test. A sample URI would be:

```text
mongodb://<AccessKeyId>:<SecretAccessKey>@localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<Token>
mongodb://localhost/?authMechanism=MONGODB-AWS
```

## Assume Role with Web Identity
Expand Down
Loading