diff --git a/source/auth/auth.md b/source/auth/auth.md index 971c01ba0b..e55886d184 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -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 @@ -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". @@ -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) @@ -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://:@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://:@mongodb.example.com/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_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 @@ -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. diff --git a/source/auth/tests/legacy/connection-string.json b/source/auth/tests/legacy/connection-string.json index 3a099c8137..8982b61d5a 100644 --- a/source/auth/tests/legacy/connection-string.json +++ b/source/auth/tests/legacy/connection-string.json @@ -440,6 +440,21 @@ } } }, + { + "description": "should throw an exception if username provided (MONGODB-AWS)", + "uri": "mongodb://user@localhost.com/?authMechanism=MONGODB-AWS", + "valid": false + }, + { + "description": "should throw an exception if username and password provided (MONGODB-AWS)", + "uri": "mongodb://user:pass@localhost.com/?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", diff --git a/source/auth/tests/legacy/connection-string.yml b/source/auth/tests/legacy/connection-string.yml index 1f5d470041..2b98f0f8f2 100644 --- a/source/auth/tests/legacy/connection-string.yml +++ b/source/auth/tests/legacy/connection-string.yml @@ -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://user@localhost.com/?authMechanism=MONGODB-AWS + valid: false +- description: should throw an exception if username and password provided (MONGODB-AWS) + uri: mongodb://user:pass@localhost.com/?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 diff --git a/source/auth/tests/mongodb-aws.md b/source/auth/tests/mongodb-aws.md index d828f7a8fe..0bd7cbe275 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 `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* 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 @@ -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 ``, `` and `` 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 @@ -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://:@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 @@ -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://:@localhost/?authMechanism=MONGODB-AWS +mongodb://localhost/?authMechanism=MONGODB-AWS ``` ## EC2 Credentials @@ -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://:@localhost/?authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN: +mongodb://localhost/?authMechanism=MONGODB-AWS ``` ## Assume Role with Web Identity