AIP-4110

Application Default Credentials

Google auth libraries use a strategy called Application Default Credentials (ADC) to detect and select credentials based on environment or context. With ADC, developers should be able to run the code in different environments and the supporting systems fetch the appropriate credentials based on each environment in an effortless manner.

Auth libraries following the standards in these AIPs are known as "Google Unified Auth Clients", or GUAC for short. The resulting libraries are colloquially called GUACs.

Note: Because this AIP describes guidance and requirements in a language-neutral way, it uses generic terminology which may be imprecise or inappropriate in certain languages or environments.

Guidance

Credential Types

This section outlines the supported credential types of the ADC.

  • Gcloud Credential: A credential provided by the Gcloud tool that identifies a human user that needs to authenticate to access Google APIs. The auth libraries must support this credential type.

  • Service Account Key: A credential that identifies a non-human user that needs to authenticate to access Google APIs. The auth libraries must support this credential type.

  • OAuth Client ID: A credential that identifies the client application which allows human users to sign-in through 3-legged OAuth flow, which grants the permissions to the application to access Google APIs on behalf of the human user. The auth libraries may support this credential type.

  • External Account Credential: A configuration file identifying external non-Google credentials that can be exchanged for Google access tokens to access Google APIs. The auth libraries must support this credential type.

Environment Variables

The auth libraries must support the following environment variables to allow developers to provide authentication configuration for their application:

  • GOOGLE_APPLICATION_CREDENTIALS: The specified value will be used as the full path for ADC to locate the credentials file. The credentials file should be one of the following types:

    • Gcloud credentials
    • Service account key
    • External account credentials

    The credentials may be the OAuth Client ID if it is supported by the auth library. Credentials file path specified at the program level (e.g. via client options) must have priority over the value of this environment variable.

  • GOOGLE_API_USE_CLIENT_CERTIFICATE: The specified value must be either true or false. The client certificate must be ignored if this variable is set to false. The default value is false if the value is unset.

GOOGLE_API_USE_CLIENT_CERTIFICATE=[true|false]
  • GOOGLE_CLOUD_QUOTA_PROJECT: The quota project id to be set on the credential. The value from the environment variable will override any quota project that is present in the credential detected by the ADC mechanism.

Inputs & Outputs

From the input/output perspective, the inputs of ADC should be the credentials as well as the underlying environment such as environment variables or metadata service that provides these credentials.

For example, the GOOGLE_APPLICATION_CREDENTIALS environment variable can provide the default credential JSON as the input here, or the well-known path that gCloud uses to store the default user credential JSON. The output is the access token that application can use to access the Google APIs. This access token may be a bearer token, a certificate-bound token, or an identity-bound token depending on the chosen authentication flow.

Expected Behavior

This section outlines the expected behavior of the ADC. Auth libraries must implement these concepts in order to be considered complete.

digraph d_front_back {
  rankdir=TB;
  ranksep=0.3;
  node [ style="filled,solid" shape=box fontname="Roboto" ];

  check_env_var [ label="1. Check Environment Variables" ];
  load_credentials [ label="2. Load Credentials" ];
  check_metadata [ label="3. Check workload credentials" ];
  auth_flows [ label="4. Determine Auth Flows" ];
  execute [ label="5. Execute Auth Flows" ];
  post_processing [ label="6. Post Processing" ];

  check_env_var -> load_credentials -> check_metadata -> auth_flows -> execute -> post_processing;
  load_credentials -> auth_flows;
  check_metadata -> post_processing;
}
  1. Check environment variables
    1. Check GOOGLE_APPLICATION_CREDENTIALS
      1. If set, go to step (2.2)
      2. If not set, go to step (2)
  2. Load credentials
    1. Check gcloud default credentials through its default path
      1. If found go to step (2.2)
      2. Otherwise go to step (3)
    2. Check the provided credential type
      1. If the credential is gcloud credentials, go to step (4)
      2. If the credential is a service account key JSON, go to step (4)
      3. If the credential is an external account JSON, go to step (4)
      4. If the credential is unknown type, return an error saying that [END]
    3. Credentials not found [END]
  3. Check workload credentials (on GCE, GKE, GAE and Serverless)
    1. If true,
      1. If identity binding is enabled, by meeting the requirements in mTLS Token Binding, use the mTLS Token Binding flow to fetch an identity-bound access token. Go to step(6).
      2. If there is an issue when obtaining bound access tokens, return an error indicating that [END]
      3. If identity binding is not enabled, use the virtual machine flow to fetch an auth token associated with the current environment
        1. If target audience is provided by the developer, get an identity token. Go to step(6).
        2. Otherwise, get an access token. Go to step(6).
    2. If false, go to step (2.3)
  4. Determine auth flows
    1. If the credential is gcloud credential go to step (5.3)
    2. If target audience or scope is provided by the developer go to step (5.1)
    3. If the credential is an external account go to step (5.4)
    4. Otherwise, go to step (5.2)
  5. Execute auth flows
    1. Use 2LO flow to exchange for an auth token
      1. If target audience is provided by the developer, get an identity token. Go to step(6).
      2. Otherwise, get an access token. Go to step(6).
        1. If client certificate is presented, the exchanged token will be a certificate bind token. Go to step(6).
    2. Use self-signed JWT flow to create an access token locally.
      1. If certificate is presented, embed the certificate into the JWT.
      2. Use the regular self-signed JWT flow for an access token. Go to step(6).
    3. Use user identity flow to exchange for an access token. Go to step(6).
    4. Use external account flow to exchange for an access token. Go to step(6).
  6. Post Processing
    1. Update Quota Project
      1. If a quota project is provided explicitly while initiating ADC, override the quota project in the credential with the explicit value. [END]
      2. Else if the GOOGLE_CLOUD_QUOTA_PROJECT environment variable is set, override the quota project in the credential with this value. [END]

Changelog

  • 2019-08-13: Add a link to virtual machine flow (AIP 4115).
  • 2019-08-18: Remove STS support from ADC.
  • 2021-01-20: Add identity token flow (AIP 4116).
  • 2021-06-29: Guidance for GOOGLE_API_KEY temporarily removed until consensus can be established.
  • 2021-12-10: Add external account credentials (AIP 4117).
  • 2023-01-23: Add Quota Project Environment variable.