diff --git a/source/auth/auth.md b/source/auth/auth.md index d96016be9e..285f150f09 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -1212,9 +1212,9 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall - mechanism_properties - - PROVIDER_NAME\ - Drivers MUST allow the user to specify the name of a built-in OIDC provider integration to use to - obtain credentials. If provided, the value MUST be one of `["aws"]`. If both `PROVIDER_NAME` and an + - ENVIRONMENT\ + Drivers MUST allow the user to specify the name of a built-in OIDC application environment integration + to use to obtain credentials. If provided, the value MUST be one of `["test"]`. If both `ENVIRONMENT` and an [OIDC Callback](#oidc-callback) or [OIDC Human Callback](#oidc-human-callback) are provided for the same `MongoClient`, the driver MUST raise an error. @@ -1243,20 +1243,25 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall performed after SRV record resolution, if applicable. This property is only required for drivers that support the [Human Authentication Flow](#human-authentication-flow). -#### Built-in Provider Integrations +
-Drivers MUST support all of the following built-in OIDC providers. +#### Built-in OIDC Environment Integrations -####### AWS +Drivers MUST support all of the following built-in OIDC application environment integrations. -The AWS provider is enabled by setting auth mechanism property `PROVIDER_NAME:aws`. +**Test** -If enabled, drivers MUST read the file path from environment variable `AWS_WEB_IDENTITY_TOKEN_FILE` and then read the -OIDC access token from that file. The driver MUST use the contents of that file as value in the `jwt` field of the -`saslStart` payload. +The test integration is enabled by setting auth mechanism property `ENVIRONMENT:test`. It is meant for driver testing +purposes, and is not meant to be documented as a user-facing feature. -Drivers MAY implement the AWS provider so that it conforms to the function signature of the -[OIDC Callback](#oidc-callback) to prevent having to re-implement the AWS provider logic in the OIDC prose tests. +If enabled, drivers MUST generate a token using a script in the `auth_oidc` +[folder](https://github.com/mongodb-labs/drivers-evergreen-tools/tree/master/.evergreen/auth_oidc#readme) in Drivers +Evergreen Tools. The must then set the `OIDC_TOKEN_FILE` environment variable to the path to that file. At runtime, the +driver MUST use the `OIDC_TOKEN_FILE` environment variable and read the OIDC access token from that path. The driver +MUST use the contents of that file as value in the `jwt` field of the `saslStart` payload. + +Drivers MAY implement the "test" integration so that it conforms to the function signature of the +[OIDC Callback](#oidc-callback) to prevent having to re-implement the "test" integration logic in the OIDC prose tests. #### OIDC Callback @@ -1916,6 +1921,8 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p ## Changelog +- 2024-03-09: Rename OIDC integration name and values. + - 2024-01-31: Migrated from reStructuredText to Markdown. - 2024-01-17: Added MONGODB-OIDC machine auth flow spec and combine with human\ diff --git a/source/auth/tests/legacy/connection-string.json b/source/auth/tests/legacy/connection-string.json index 982edb8b36..a5f3c7e085 100644 --- a/source/auth/tests/legacy/connection-string.json +++ b/source/auth/tests/legacy/connection-string.json @@ -482,8 +482,8 @@ } }, { - "description": "should recognise the mechanism with aws provider (MONGODB-OIDC)", - "uri": "mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=PROVIDER_NAME:aws", + "description": "should recognise the mechanism with test integration (MONGODB-OIDC)", + "uri": "mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:test", "valid": true, "credential": { "username": null, @@ -491,13 +491,13 @@ "source": "$external", "mechanism": "MONGODB-OIDC", "mechanism_properties": { - "PROVIDER_NAME": "aws" + "ENVIRONMENT": "test" } } }, { - "description": "should recognise the mechanism when auth source is explicitly specified and with provider (MONGODB-OIDC)", - "uri": "mongodb://localhost/?authMechanism=MONGODB-OIDC&authSource=$external&authMechanismProperties=PROVIDER_NAME:aws", + "description": "should recognise the mechanism when auth source is explicitly specified and with environment (MONGODB-OIDC)", + "uri": "mongodb://localhost/?authMechanism=MONGODB-OIDC&authSource=$external&authMechanismProperties=ENVIRONMENT:test", "valid": true, "credential": { "username": null, @@ -505,30 +505,30 @@ "source": "$external", "mechanism": "MONGODB-OIDC", "mechanism_properties": { - "PROVIDER_NAME": "aws" + "ENVIRONMENT": "test" } } }, { "description": "should throw an exception if supplied a password (MONGODB-OIDC)", - "uri": "mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=PROVIDER_NAME:aws", + "uri": "mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:test", "valid": false, "credential": null }, { - "description": "should throw an exception if username is specified for aws (MONGODB-OIDC)", - "uri": "mongodb://principalName@localhost/?authMechanism=MONGODB-OIDC&PROVIDER_NAME:aws", + "description": "should throw an exception if username is specified for test (MONGODB-OIDC)", + "uri": "mongodb://principalName@localhost/?authMechanism=MONGODB-OIDC&ENVIRONMENT:test", "valid": false, "credential": null }, { - "description": "should throw an exception if specified provider is not supported (MONGODB-OIDC)", - "uri": "mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=PROVIDER_NAME:invalid", + "description": "should throw an exception if specified environment is not supported (MONGODB-OIDC)", + "uri": "mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:invalid", "valid": false, "credential": null }, { - "description": "should throw an exception if neither provider nor callbacks specified (MONGODB-OIDC)", + "description": "should throw an exception if neither environment nor callbacks specified (MONGODB-OIDC)", "uri": "mongodb://localhost/?authMechanism=MONGODB-OIDC", "valid": false, "credential": null diff --git a/source/auth/tests/legacy/connection-string.yml b/source/auth/tests/legacy/connection-string.yml index d2658e0309..8c3d46d01a 100644 --- a/source/auth/tests/legacy/connection-string.yml +++ b/source/auth/tests/legacy/connection-string.yml @@ -350,8 +350,8 @@ tests: mechanism: MONGODB-AWS mechanism_properties: AWS_SESSION_TOKEN: token!@#$%^&*()_+ -- description: should recognise the mechanism with aws provider (MONGODB-OIDC) - uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=PROVIDER_NAME:aws +- description: should recognise the mechanism with test environment (MONGODB-OIDC) + uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:test valid: true credential: username: @@ -359,9 +359,9 @@ tests: source: "$external" mechanism: MONGODB-OIDC mechanism_properties: - PROVIDER_NAME: aws -- description: should recognise the mechanism when auth source is explicitly specified and with provider (MONGODB-OIDC) - uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authSource=$external&authMechanismProperties=PROVIDER_NAME:aws + ENVIRONMENT: test +- description: should recognise the mechanism when auth source is explicitly specified and with environment (MONGODB-OIDC) + uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authSource=$external&authMechanismProperties=ENVIRONMENT:test valid: true credential: username: @@ -369,20 +369,20 @@ tests: source: "$external" mechanism: MONGODB-OIDC mechanism_properties: - PROVIDER_NAME: aws + ENVIRONMENT: test - description: should throw an exception if supplied a password (MONGODB-OIDC) - uri: mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=PROVIDER_NAME:aws + uri: mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:test valid: false credential: - description: should throw an exception if username is specified for aws (MONGODB-OIDC) - uri: mongodb://principalName@localhost/?authMechanism=MONGODB-OIDC&PROVIDER_NAME:aws + uri: mongodb://principalName@localhost/?authMechanism=MONGODB-OIDC&ENVIRONMENT:test valid: false credential: -- description: should throw an exception if specified provider is not supported (MONGODB-OIDC) - uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=PROVIDER_NAME:invalid +- description: should throw an exception if specified environment is not supported (MONGODB-OIDC) + uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:invalid valid: false credential: -- description: should throw an exception if neither provider nor callbacks specified (MONGODB-OIDC) +- description: should throw an exception if neither environment nor callbacks specified (MONGODB-OIDC) uri: mongodb://localhost/?authMechanism=MONGODB-OIDC valid: false credential: diff --git a/source/auth/tests/mongodb-oidc.md b/source/auth/tests/mongodb-oidc.md index f0a2053b2a..86d0c7d120 100644 --- a/source/auth/tests/mongodb-oidc.md +++ b/source/auth/tests/mongodb-oidc.md @@ -14,7 +14,7 @@ For example, if the selected AWS profile ID is "drivers-test", run: aws configure sso export OIDC_TOKEN_DIR=/tmp/tokens AWS_PROFILE="drivers-test" oidc_get_tokens.sh -AWS_WEB_IDENTITY_TOKEN_FILE="$OIDC_TOKEN_DIR/test_user1" /my/test/command +OIDC_TOKEN_FILE="$OIDC_TOKEN_DIR/test_user1" /my/test/command ``` ______________________________________________________________________ @@ -26,7 +26,7 @@ configured with `retryReads=false`. > [!NOTE] > For test cases that create fail points, drivers MUST either use a unique `appName` or explicitly remove the fail point -> after the test to prevent interaction between test cases. +> callback to prevent interaction between test cases. Note that typically the preconfigured Atlas Dev clusters are used for testing, in Evergreen and locally. The URIs can be fetched from the `drivers/oidc` Secrets vault, see @@ -35,18 +35,18 @@ Use `OIDC_ATLAS_URI_SINGLE` for the `MONGODB_URI`. If using local servers is pre [Local Testing](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/README.md#local-testing) method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI`. -### (1) OIDC Callback Authentication +### Callback Authentication **1.1 Callback is called during authentication** -- Create a `MongoClient` configured with an OIDC callback that implements the AWS provider logic. +- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic. - Perform a `find` operation that succeeds. - Assert that the callback was called 1 time. - Close the client. **1.2 Callback is called once for multiple connections** -- Create a `MongoClient` configured with an OIDC callback that implements the AWS provider logic. +- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic. - Start 10 threads and run 100 `find` operations in each thread that all succeed. - Assert that the callback was called 1 time. - Close the client. @@ -75,14 +75,14 @@ method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI`. **2.4 Invalid Client Configuration with Callback** -- Create a `MongoClient` configured with an OIDC callback and auth mechanism property `PROVIDER_NAME:aws`. +- Create a `MongoClient` configured with an OIDC callback and auth mechanism property `ENVIRONMENT:test`. - Assert it returns a client configuration error. ### (3) Authentication Failure **3.1 Authentication failure with cached tokens fetch a new token and retry auth** -- Create a `MongoClient` configured with an OIDC callback that implements the AWS provider logic. +- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic. - Poison the *Client Cache* with an invalid access token. - Perform a `find` operation that succeeds. - Assert that the callback was called 1 time. @@ -97,7 +97,7 @@ method, use `mongodb://localhost/?authMechanism=MONGODB-OIDC` for `MONGODB_URI`. ### (4) Reauthentication -- Create a `MongoClient` configured with an OIDC callback that implements the AWS provider logic. +- Create a `MongoClient` configured with an OIDC callback that implements the `ENVIRONMENT:test` logic. - Set a fail point for `find` commands of the form: ```javascript diff --git a/source/auth/tests/unified/mongodb-oidc-no-retry.yml b/source/auth/tests/unified/mongodb-oidc-no-retry.yml index b500fb7db6..8108acb501 100644 --- a/source/auth/tests/unified/mongodb-oidc-no-retry.yml +++ b/source/auth/tests/unified/mongodb-oidc-no-retry.yml @@ -15,8 +15,8 @@ createEntities: authMechanism: "MONGODB-OIDC" # The $$placeholder document should be replaced by auth mechanism # properties that enable OIDC auth on the target cloud platform. For - # example, when running the test on AWS, replace the $$placeholder - # document with {"PROVIDER_NAME": "aws"}. + # example, when running the test on EC2, replace the $$placeholder + # document with {"ENVIRONMENT": "test"}. authMechanismProperties: { $$placeholder: 1 } retryReads: false retryWrites: false diff --git a/source/unified-test-format/unified-test-format.md b/source/unified-test-format/unified-test-format.md index 7b258084e8..97b52a4193 100644 --- a/source/unified-test-format/unified-test-format.md +++ b/source/unified-test-format/unified-test-format.md @@ -422,7 +422,7 @@ The structure of this object is as follows: uriOptions: authMechanism: "MONGODB-OIDC" authMechanismProperties: - PROVIDER_NAME: { $$placeholder: 1 } + ENVIRONMENT: { $$placeholder: 1 } ```