DRIVERS-2601 OIDC: Automatic token acquisition for GCP Identity Provider

source/auth/auth.md

@@ -1214,14 +1214,15 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall
 
  - 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", "azure"]`. 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.
+ to use to obtain credentials. If provided, the value MUST be one of `["test", "azure", "gcp"]`. 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.
 
  - TOKEN_RESOURCE\
  The URI of the target resource. This property is currently only used and required by the Azure
- built-in OIDC provider integration. If `TOKEN_RESOURCE` is provided and `ENVIRONMENT` is not `azure` or
- `TOKEN_RESOURCE` is not provided and `ENVIRONMENT` is `azure`, the driver MUST raise an error.
+ built-in OIDC provider integration. If `TOKEN_RESOURCE` is provided and `ENVIRONMENT` is not one of
+ `["azure", "gcp"]` or `TOKEN_RESOURCE` is not provided and `ENVIRONMENT` is one of `["azure", "gcp"]`, the driver
+ MUST raise an error.
 
  - OIDC_CALLBACK\
  An [OIDC Callback](#oidc-callback) that returns OIDC credentials. Drivers MAY allow the user to
@@ -1326,6 +1327,67 @@ For more details, see
 The callback itself MUST not perform any caching, and the driver MUST cache its tokens in the same way as if a custom
 callback had been provided by the user.
 
+For details on test environment setup, see the README in
+[Drivers-Evergreen-Tools](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/azure/README.md).
+
+**GCP**
+
+The GCP provider integration is enabled by setting auth mechanism property `ENVIRONMENT:gcp`.
+
+If enabled, drivers MUST use an internal machine callback that calls the
+[Google Cloud VM metadata](https://cloud.google.com/compute/docs/metadata/overview) endpoint and parse the JSON response
+body, as follows:
+
+Make an HTTP GET request to
+
+```
+http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=<resource>
+```
+
+with headers
+
+```
+Accept: application/json
+Metadata-Flavor: Google
+```
+
+where `<resource>` is the value of the `TOKEN_RESOURCE` mechanism property. The timeout should equal the
+`callbackTimeoutMS` parameter given to the callback.
+
+Example code for the above using curl, where `$TOKEN_RESOURCE` is the value of the `TOKEN_RESOURCE` mechanism property.
+
+```bash
+curl -X GET \
+ -H "Accept: application/json" \
+ -H "Metadata-Flavor: Google" \
+ --max-time $CALLBACK_TIMEOUT_MS \
+ "http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=$TOKEN_RESOURCE"
+```
+
+The JSON response will be in this format:
+
+```json
+{
+ "aud": "https://example.com",
+ "azp": "118153013249117554930",
+ "exp": 1707488566,
+ "iat": 1707484966,
+ "iss": "https://accounts.google.com",
+ "sub": "118153013249117554930"
+}
+```
+
+The driver MUST use the returned `"access_token"` value as the access token in a `JwtStepRequest`. If the response does
+not return a status code of 200, the driver MUST raise an error including the HTTP response body.
+
+For more details, see [View and query VM metadata](https://cloud.google.com/compute/docs/metadata/querying-metadata).
+
+The callback itself MUST not perform any caching, and the driver MUST cache its tokens in the same way as if a custom
+callback had been provided by the user.
+
+For details on test environment setup, see the README in
+[Drivers-Evergreen-Tools](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/auth_oidc/gcp/README.md).
+
 #### OIDC Callback
 
 Drivers MUST allow users to provide a callback that returns an OIDC access token. The purpose of the callback is to
@@ -1988,6 +2050,8 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p
 
 ## Changelog
 
+- 2024-04-03: Added GCP built-in OIDC provider integration.
+
 - 2024-03-29: Updated OIDC test setup and descriptions.
 
 - 2024-03-21: Added Azure built-in OIDC provider integration.

source/auth/tests/legacy/connection-string.yml

@@ -390,3 +390,53 @@ tests:
  uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=UnsupportedProperty:unexisted
  valid: false
  credential:
+- description: should recognise the mechanism with azure provider (MONGODB-OIDC)
+ uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:foo
+ valid: true
+ credential:
+ username: null
+ password: null
+ source: $external
+ mechanism: MONGODB-OIDC
+ mechanism_properties:
+ ENVIRONMENT: azure
+ TOKEN_RESOURCE: foo
+- description: should accept a username with azure provider (MONGODB-OIDC)
+ uri: mongodb://user@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:foo
+ valid: true
+ credential:
+ username: user
+ password: null
+ source: $external
+ mechanism: MONGODB-OIDC
+ mechanism_properties:
+ ENVIRONMENT: azure
+ TOKEN_RESOURCE: foo
+- description: should accept a username and throw an error for a password with azure provider (MONGODB-OIDC)
+ uri: mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:foo
+ valid: false
+ credential: null
+- description: should throw an exception if no token audience is given for azure provider (MONGODB-OIDC)
+ uri: mongodb://username@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:azure
+ valid: false
+ credential: null
+- description: should recognise the mechanism with gcp provider (MONGODB-OIDC)
+ uri: mongodb://localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:foo
+ valid: true
+ credential:
+ username: null
+ password: null
+ source: $external
+ mechanism: MONGODB-OIDC
+ mechanism_properties:
+ ENVIRONMENT: gcp
+ TOKEN_RESOURCE: foo
+- description: should throw an error for a username and password with gcp provider
+ (MONGODB-OIDC)
+ uri: mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:foo
+ valid: false
+ credential: null
+- description: should throw an error if not TOKEN_RESOURCE with gcp provider (MONGODB-OIDC)
+ uri: mongodb://user:pass@localhost/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp
+ valid: false
+ credential: null