google.auth.external_account module

External Account Credentials.

This module provides credentials that exchange workload identity pool external credentials for Google access tokens. This facilitates accessing Google Cloud Platform resources from on-prem and non-Google Cloud platforms (e.g. AWS, Microsoft Azure, OIDC identity providers), using native credentials retrieved from the current environment without the need to copy, save and manage long-lived service account credentials.

Specifically, this is intended to use access tokens acquired using the GCP STS token exchange endpoint following the OAuth 2.0 Token Exchange spec.

class Credentials(audience, subject_token_type, token_url, credential_source, service_account_impersonation_url=None, client_id=None, client_secret=None, quota_project_id=None, scopes=None, default_scopes=None)[source]

Bases: google.auth.credentials.Scoped, google.auth.credentials.CredentialsWithQuotaProject

Base class for all external account credentials.

This is used to instantiate Credentials for exchanging external account credentials for Google access token and authorizing requests to Google APIs. The base class implements the common logic for exchanging external account credentials for Google access tokens.

Instantiates an external account credentials object.

Parameters

  • audience (str) – The STS audience field.

  • subject_token_type (str) – The subject token type.

  • token_url (str) – The STS endpoint URL.

  • credential_source (Mapping) – The credential source dictionary.

  • service_account_impersonation_url (Optional [ str ]) – The optional service account impersonation generateAccessToken URL.

  • client_id (Optional [ str ]) – The optional client ID.

  • client_secret (Optional [ str ]) – The optional client secret.

  • quota_project_id (Optional [ str ]) – The optional quota project ID.

  • scopes (Optional [ Sequence [ str ] ]) – Optional scopes to request during the authorization grant.

  • default_scopes (Optional [ Sequence [ str ] ]) – Default scopes passed by a Google client library. Use ‘scopes’ for user-defined scopes.

Raises

google.auth.exceptions.RefreshError – If the generateAccessToken endpoint returned an error.

property requires_scopes

Checks if the credentials requires scopes.

Returns

True if there are no scopes set otherwise False.

Return type

bool

property project_number

The project number corresponding to the workload identity pool.

Type

Optional [ str ]

with_scopes(scopes, default_scopes=None)[source]

Create a copy of these credentials with the specified scopes.

Parameters

scopes (Sequence [ str ]) – The list of scopes to attach to the current credentials.

Raises

NotImplementedError – If the credentials’ scopes can not be changed. This can be avoided by checking requires_scopes before calling this method.

abstract retrieve_subject_token(request)[source]

Retrieves the subject token using the credential_source object.

Parameters

request (google.auth.transport.Request) – A callable used to make HTTP requests.

Returns

The retrieved subject token.

Return type

str

get_project_id(request)[source]

Retrieves the project ID corresponding to the workload identity pool.

When not determinable, None is returned.

This is introduced to support the current pattern of using the Auth library:

credentials, project_id = google.auth.default()

The resource may not have permission (resourcemanager.projects.get) to call this API or the required scopes may not be selected: https://cloud.google.com/resource-manager/reference/rest/v1/projects/get#authorization-scopes

Parameters

request (google.auth.transport.Request) – A callable used to make HTTP requests.

Returns

The project ID corresponding to the workload identity pool

if determinable.

Return type

Optional [ str ]

refresh(request)[source]

Refreshes the access token.

Parameters

request (google.auth.transport.Request) – The object used to make HTTP requests.

Raises

google.auth.exceptions.RefreshError – If the credentials could not be refreshed.

apply(headers, token=None)[source]

Apply the token to the authentication header.

Parameters

  • headers (Mapping) – The HTTP request headers.

  • token (Optional [ str ]) – If specified, overrides the current access token.

before_request(request, method, url, headers)[source]

Performs credential-specific before request logic.

Refreshes the credentials if necessary, then calls apply() to apply the token to the authentication header.

Parameters

  • request (google.auth.transport.Request) – The object used to make HTTP requests.

  • method (str) – The request’s HTTP method or the RPC method being invoked.

  • url (str) – The request’s URI or the RPC service’s URI.

  • headers (Mapping) – The request’s headers.

property default_scopes

the credentials’ current set of default scopes.

Type

Sequence [ str ]

property expired

Checks if the credentials are expired.

Note that credentials can be invalid but not expired because Credentials with expiry set to None is considered to never expire.

has_scopes(scopes)

Checks if the credentials have the given scopes.

Parameters

scopes (Sequence [ str ]) – The list of scopes to check.

Returns

True if the credentials have the given scopes.

Return type

bool

property quota_project_id

Project to use for quota and billing purposes.

property scopes

the credentials’ current set of scopes.

Type

Sequence [ str ]

property valid

Checks the validity of the credentials.

This is True if the credentials have a token and the token is not expired.

with_quota_project(quota_project_id)[source]

Returns a copy of these credentials with a modified quota project.

Parameters

quota_project_id (str) – The project to use for quota and billing purposes

Returns

A new credentials instance.

Return type

google.oauth2.credentials.Credentials