google.auth.identity_pool module

Identity Pool Credentials.

This module provides credentials to access Google Cloud resources from on-prem or non-Google Cloud platforms which support external credentials (e.g. OIDC ID tokens) retrieved from local file locations or local servers. This includes Microsoft Azure and OIDC identity providers (e.g. K8s workloads registered with Hub with Hub workload identity enabled).

These credentials are recommended over the use of service account credentials in on-prem/non-Google Cloud platforms as they do not involve the management of long-live service account private keys.

Identity Pool Credentials are initialized using external_account arguments which are typically loaded from an external credentials file or an external credentials URL. Unlike other Credentials that can be initialized with a list of explicit arguments, secrets or credentials, external account clients use the environment and hints/guidelines provided by the external_account JSON file to retrieve credentials and exchange them for Google access tokens.

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, workforce_pool_user_project=None)[source]

Bases: google.auth.external_account.Credentials

External account credentials sourced from files and URLs.

Instantiates an external account credentials object from a file/URL.

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 used to provide instructions on how to retrieve external credential to be exchanged for Google access tokens.

    Example credential_source for url-sourced credential:

    {
        "url": "http://www.example.com",
        "format": {
            "type": "json",
            "subject_token_field_name": "access_token",
        },
        "headers": {"foo": "bar"},
    }
    

    Example credential_source for file-sourced credential:

    {
        "file": "/path/to/token/file.txt"
    }
    

  • service_account_impersonation_url (Optional [ str ]) – The optional service account impersonation getAccessToken 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.

  • 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.

Raises

Note

Typically one of the helper constructors from_file() or from_info() are used instead of calling the constructor directly.

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

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.

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

Optional [ str ]

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 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 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 project_number

The project number corresponding to the workload identity pool.

Type

Optional [ str ]

property quota_project_id

Project to use for quota and billing purposes.

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.

property requires_scopes

Checks if the credentials requires scopes.

Returns

True if there are no scopes set otherwise False.

Return type

bool

property scopes

the credentials’ current set of scopes.

Type

Sequence [ str ]

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

Optional [ 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

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.

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

Optional [ datetime ]

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

Creates an Identity Pool Credentials instance from parsed external account info.

Parameters
  • info (Mapping [ str, str ]) – The Identity Pool 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

ValueError – For invalid parameters.

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

Creates an IdentityPool Credentials instance from an external account json file.

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

  • kwargs – Additional arguments to pass to the constructor.

Returns

The constructed

credentials.

Return type

google.auth.identity_pool.Credentials