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 SupplierContext(subject_token_type: str, audience: str)[source]

Bases: object

A context class that contains information about the requested third party credential that is passed to AWS security credential and subject token suppliers.

subject_token_type

The requested subject token type based on the Oauth2.0 token exchange spec. Expected values include:

“urn:ietf:params:oauth:token-type:jwt”
“urn:ietf:params:oauth:token-type:id-token”
“urn:ietf:params:oauth:token-type:saml2”
“urn:ietf:params:aws:token-type:aws4_request”
Type:

str

audience

The requested audience for the subject token.

Type:

str

class Credentials(audience, subject_token_type, token_url, credential_source, service_account_impersonation_url=None, service_account_impersonation_options=None, client_id=None, client_secret=None, token_info_url=None, quota_project_id=None, scopes=None, default_scopes=None, workforce_pool_user_project=None, universe_domain='googleapis.com', trust_boundary=None)[source]

Bases: Scoped, CredentialsWithQuotaProject, CredentialsWithTokenUri

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 based on the Oauth2.0 token exchange spec. Expected values include:

    “urn:ietf:params:oauth:token-type:jwt”
“urn:ietf:params:oauth:token-type:id-token”
“urn:ietf:params:oauth:token-type:saml2”
“urn:ietf:params:aws:token-type:aws4_request”

  • token_url (str) – The STS endpoint URL.

  • credential_source (Mapping) – The credential source dictionary.

  • service_account_impersonation_url (Optionalstr) – The optional service account impersonation generateAccessToken URL.

  • client_id (Optionalstr) – The optional client ID.

  • client_secret (Optionalstr) – The optional client secret.

  • token_info_url (str) – The optional STS endpoint URL for token introspection.

  • quota_project_id (Optionalstr) – The optional quota project ID.

  • scopes (OptionalSequencestr) – Optional scopes to request during the authorization grant.

  • default_scopes (OptionalSequencestr) – Default scopes passed by a Google client library. Use ‘scopes’ for user-defined scopes.

  • workforce_pool_user_project (Optona[str]) – The optional workforce pool user project number when the credential corresponds to a workforce pool and not a workload identity pool. The underlying principal must still have serviceusage.services.use IAM permission to use the project for billing/quota.

  • universe_domain (str) – The universe domain. The default universe domain is googleapis.com.

  • trust_boundary (str) – String representation of trust boundary meta.

Raises:

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

property info

Generates the dictionary representation of the current credentials.

Returns:

The dictionary representation of the credentials. This is the

reverse of “from_info” defined on the subclasses of this class. It is useful for serializing the current credentials so it can deserialized later.

Return type:

Mapping

property service_account_email

Returns the service account email if service account impersonation is used.

Returns:

The service account email if impersonation is used. Otherwise

None is returned.

Return type:

Optionalstr

property is_user

Returns whether the credentials represent a user (True) or workload (False). Workloads behave similarly to service accounts. Currently workloads will use service account impersonation but will eventually not require impersonation. As a result, this property is more reliable than the service account email property in determining if the credentials represent a user or workload.

Returns:

True if the credentials represent a user. False if they represent a

workload.

Return type:

bool

property is_workforce_pool

Returns whether the credentials represent a workforce pool (True) or workload (False) based on the credentials’ audience.

This will also return True for impersonated workforce pool credentials.

Returns:

True if the credentials represent a workforce pool. False if they

represent a workload.

Return type:

bool

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:

Optionalstr

property token_info_url

The STS token introspection endpoint.

Type:

Optionalstr

with_scopes(scopes, default_scopes=None)[source]

Create a copy of these credentials with the specified scopes.

Parameters:

scopes (Sequencestr) – 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 or workforce pool. For workforce pool credentials, it returns the project ID corresponding to the workforce_pool_user_project.

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

or workforce pool if determinable.

Return type:

Optionalstr

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.

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.auth.credentials.Credentials

with_token_uri(token_uri)[source]

Returns a copy of these credentials with a modified token uri.

Parameters:

token_uri (str) – The uri to use for fetching/exchanging tokens

Returns:

A new credentials instance.

Return type:

google.auth.credentials.Credentials

with_universe_domain(universe_domain)[source]

Returns a copy of these credentials with a modified universe domain.

Parameters:

universe_domain (str) – The universe domain to use

Returns:

A new credentials instance.

Return type:

google.auth.credentials.Credentials

apply(headers, token=None)[source]

Apply the token to the authentication header.

Parameters:

  • headers (Mapping) – The HTTP request headers.

  • token (Optionalstr) – 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:

Sequencestr

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.

Deprecated since version v2.24.0: Prefer checking token_state instead.

classmethod from_info(info, **kwargs)[source]

Creates a Credentials instance from parsed external account info.

Parameters:

  • info (Mappingstr, str) – The external account info in Google format.

  • kwargs – Additional arguments to pass to the constructor.

Returns:

The constructed

credentials.

Return type:

google.auth.identity_pool.Credentials

Raises:

InvalidValue – For invalid parameters.

has_scopes(scopes)

Checks if the credentials have the given scopes.

Parameters:

scopes (Sequencestr) – 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:

Sequencestr

property token_state

See :obj:`TokenState

property universe_domain

The universe domain value.

property valid

Checks the validity of the credentials.

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

Deprecated since version v2.24.0: Prefer checking token_state instead.

token

The bearer token that can be used in HTTP headers to make authenticated requests.

Type:

str

expiry

When the token expires and is no longer valid. If this is None, the token is assumed to never expire.

Type:

Optionaldatetime

classmethod from_file(filename, **kwargs)[source]

Creates a Credentials instance from an external account json file.

Parameters:

  • filename (str) – The path to the external account json file.

  • kwargs – Additional arguments to pass to the constructor.

Returns:

The constructed

credentials.

Return type:

google.auth.identity_pool.Credentials