forked from aip-dev/google.aip.dev
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[AIP-4117] Document executable-sourced credentials. (aip-dev#896)
- Loading branch information
Showing
1 changed file
with
123 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -192,7 +192,7 @@ The JSON file for AWS configuration files should have the following form: | |
| "environment_id": "aws1", | ||
| "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone", | ||
| "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials", | ||
| "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15", | ||
| "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15" | ||
| } | ||
| } | ||
| ``` | ||
|
|
@@ -331,7 +331,7 @@ The auth libraries and applications **must** follow the steps below: | |
| - Parse the file as JSON and then retrieve the external credential from | ||
| the field name based on the value of **subject_token_field_name**. | ||
|
|
||
| #### Determining the subject token file-sourced credentials | ||
| #### Determining the subject token in file-sourced credentials | ||
|
|
||
| External account configuration JSON files contain the following information | ||
| in the `credential_source` object to facilitate retrieval of file-sourced | ||
|
|
@@ -362,11 +362,10 @@ the following form: | |
|
|
||
| The auth libraries and applications **must** follow the steps below: | ||
|
|
||
| - Check **credential_source** for the environment ID. If no environment ID, | ||
| this should be a file-sourced credential. | ||
| - Check **credential_source** has a **file** field and no **environment_id**. If not, | ||
| this is not a file-sourced credential and the proceeding steps do not apply. | ||
| - Get the external credential from the file location specified by the | ||
| `credential_source.file` field. If not available, this should be a | ||
| url-sourced credential. | ||
| `credential_source.file` field. | ||
| - Before parsing the token, check the **format** field. | ||
| - If the **format** is not available, assume the external credential is | ||
| provided in plain text format. | ||
|
|
@@ -375,10 +374,127 @@ The auth libraries and applications **must** follow the steps below: | |
| - Parse the file as JSON and then retrieve the external credential from | ||
| the field name based on the value of **subject_token_field_name**. | ||
|
|
||
|
|
||
| #### Determining the subject token in executable-sourced credentials | ||
|
|
||
| External account configuration JSON files contain the following information | ||
| in the `credential_source` object to facilitate retrieval of executable-sourced | ||
| credentials to be passed as subject tokens to the GCP STS token exchange | ||
| endpoint. | ||
|
|
||
| | Field Name | Required | Description | | ||
| |---------------------------|----------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | executable | Yes | Holds the information necessary to run the executable. | | ||
| | executable.command | Yes | Specifies the full command to run to retrieve the subject token. This can include arguments. Must be an absolute path for the program. | | ||
| | executable.timeout_millis | No | Specifies the timeout duration, in milliseconds. Defaults to 30 seconds when not provided. | | ||
| | executable.output_file | No | Specifies the absolute path to the output file where the executable will cache the response. By specifying this path, the auth libraries will first check this location before running the executable. The format of the file should match the JSON format expected by the auth libraries defined below. | | ||
|
|
||
| The JSON file for executable-sourced configuration files (OIDC / SAML) should have | ||
| the following form: | ||
|
|
||
| ```json | ||
| { | ||
| "type": "external_account", | ||
| "audience": "//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID", | ||
| "subject_token_type": "urn:ietf:params:oauth:token-type:saml2", | ||
| "token_url": "https://sts.googleapis.com/v1/token", | ||
| "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[email protected]:generateAccessToken", | ||
| "credential_source": { | ||
| "executable": { | ||
| "command": "/path/to/executable --arg1=value1 --arg2=value2", | ||
| "timeout_millis": 5000, | ||
| "output_file": "/path/to/cached/credentials" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| To use executable-sourced credentials, the `GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES` environment variable must be set to `1`. | ||
|
|
||
| Additionally, the executable **must** adhere to the following response format: | ||
|
|
||
| Successful responses: | ||
|
|
||
| | Field Name | Type | Description | | ||
| |---------------------------|---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | version | number | The version of the JSON output. Currently only version 1 is supported. | | ||
| | success | boolean | The status of the response. True in this case. | | ||
| | token_type | string | The 3rd party subject token type. Must be *urn:ietf:params:oauth:token-type:jwt*, *urn:ietf:params:oauth:token-type:id_token*, or *urn:ietf:params:oauth:token-type:saml2*. | | ||
| | id_token OR saml_response | string | The 3rd party OIDC token or SAML response. | | ||
| | expiration_time | number | The 3rd party subject token expiration time in seconds (unix epoch time). | | ||
|
|
||
| A sample successful executable OIDC response: | ||
| ```json | ||
| { | ||
| "version": 1, | ||
| "success": true, | ||
| "token_type": "urn:ietf:params:oauth:token-type:id_token", | ||
| "id_token": "...", | ||
| "expiration_time": 1620499962 | ||
| } | ||
| ``` | ||
|
|
||
| A sample successful executable SAML response: | ||
| ```json | ||
| { | ||
| "version": 1, | ||
| "success": true, | ||
| "token_type": "urn:ietf:params:oauth:token-type:saml2", | ||
| "saml_response": "...", | ||
| "expiration_time": 1620499962 | ||
| } | ||
| ``` | ||
|
|
||
| Error responses: | ||
|
|
||
| | Field Name | Type | Description | | ||
| |------------|---------|:-----------------------------------------------------------------------| | ||
| | version | number | The version of the JSON output. Currently only version 1 is supported. | | ||
| | success | boolean | The status of the response. False in this case. | | | ||
| | code | string | The error code. | | ||
| | message | string | The error message. | | ||
|
|
||
| A sample executable error response: | ||
| ```json | ||
| { | ||
| "version": 1, | ||
| "success": false, | ||
| "code": "401", | ||
| "message": "Caller not authorized." | ||
| } | ||
| ``` | ||
|
|
||
| The auth libraries and applications **must** follow the steps below: | ||
|
|
||
| - Check **credential_source** has an **executable** field and no **environment_id**. If not, | ||
| this is not a executable-sourced credential and the proceeding steps do not apply. | ||
| - Retrieve the external credential's executable information from the | ||
| **credential_source.executable** field. | ||
| - Check that the `GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES` environment variable is set to **1**. If not, error out. | ||
| - Before the next step, check if **credential_source.executable.output_file** was specified in the credential configuration. | ||
| - If present, check if there is an executable response at that location. | ||
| - If the response is valid and unexpired, or there is no response at that location, continue execution. | ||
| - If the response is malformed or invalid, error out. | ||
| - Ensure the following environment variables will be available to the executable: | ||
| - `GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE`: The audience field from the credential configuration. Must always be present. | ||
| - `GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL`: The service account email. Only present when service account impersonation is used. | ||
| - `GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE`: The output file location from the credential configuration. Only present when specified in the credential configuration. | ||
| - Run the command specified at **credential_source.executable.command**. | ||
| - Fail in the following scenarios: | ||
| - The executable failed to complete in the timeout duration specified. | ||
| - The executable's response is invalid, was unsuccessful or expired. | ||
| - The executable finished with a non-zero exit code. | ||
| - Parse the executable response as JSON and then retrieve the external credential from | ||
| the field name based on the value of **token_type**. | ||
| - The token_type value must be **urn:ietf:params:oauth:token-type:jwt**, | ||
| **urn:ietf:params:oauth:token-type:id_token**, or **urn:ietf:params:oauth:token-type:saml2**. | ||
| - If the **token_type** is **urn:ietf:params:oauth:token-type:saml2**, the subject token will be parsed from the **saml_response** field. | ||
| - Otherwise it will be parsed from the **id_token** field. | ||
|
|
||
| ## Changelog | ||
|
|
||
| - **2021-12-10**: Add AIP for External Account Credentials (AIP 4117). | ||
|
|
||
| - **2022-05-18**: Document executable-sourced credentials (AIP 4117). | ||
|
|
||
| <!-- prettier-ignore-start --> | ||
| [0]: https://cloud.google.com/iam/docs/configuring-workload-identity-federation#aws | ||
|
|
||