PluggableAuthClient

PluggableAuthClient enables the exchange of workload identity pool external credentials for Google access tokens by retrieving 3rd party tokens through a user supplied executable. These scripts/executables are completely independent of the Google Cloud Auth libraries. These credentials plug into ADC and will call the specified executable to retrieve the 3rd party token to be exchanged for a Google access token.

To use these credentials, the GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES environment variable must be set to '1'. This is for security reasons.

Both OIDC and SAML are supported. The executable must adhere to a specific response format defined below.

The executable must print out the 3rd party token to STDOUT in JSON format. When an output_file is specified in the credential configuration, the executable must also handle writing the JSON response to this file.

OIDC response sample:
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620433341
}

SAML2 response sample:
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620433341
}

Error response sample:
{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Error message."
}

The "expiration_time" field in the JSON response is only required for successful responses when an output file was specified in the credential configuration

The auth libraries will populate certain environment variables that will be accessible by the executable, such as: GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE, GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE, GOOGLE_EXTERNAL_ACCOUNT_INTERACTIVE, GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL, and GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE.

Please see this repositories README for a complete executable request/response specification.

Constructor

new PluggableAuthClient(options)

Instantiates a PluggableAuthClient instance using the provided JSON object loaded from an external account credentials file. An error is thrown if the credential is not a valid pluggable auth credential.

Parameters:

Name	Type	Description
`options`		The external account options object typically loaded from the external account JSON credential file.

Members

command

The command used to retrieve the third party token.

handler

Executable and output file handler.

outputFile

The path to file to check for cached executable response.

timeoutMillis

The timeout in milliseconds for running executable, set to default if none provided.

Methods

(async) retrieveSubjectToken()

Triggered when an external subject token is needed to be exchanged for a GCP access token via GCP STS endpoint. This uses the options.credential_source object to figure out how to retrieve the token using the current environment. In this case, this calls a user provided executable which returns the subject token. The logic is summarized as:

Validated that the executable is allowed to run. The GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES environment must be set to 1 for security reasons.
If an output file is specified by the user, check the file location for a response. If the file exists and contains a valid response, return the subject token from the file.
Call the provided executable and return response.

Returns:

Type	Description
	A promise that resolves with the external subject token.