google.auth.impersonated_credentials module

Google Cloud Impersonated credentials.

This module provides authentication for applications where local credentials impersonates a remote service account using IAM Credentials API.

This class can be used to impersonate a service account as long as the original Credential object has the “Service Account Token Creator” role on the target service account.

class Credentials(source_credentials, target_principal, target_scopes, delegates=None, subject=None, lifetime=3600, quota_project_id=None, iam_endpoint_override=None)[source]

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

This module defines impersonated credentials which are essentially impersonated identities.

Impersonated Credentials allows credentials issued to a user or service account to impersonate another. The target service account must grant the originating credential principal the Service Account Token Creator IAM role:

For more information about Token Creator IAM role and IAMCredentials API, see Creating Short-Lived Service Account Credentials.

Usage:

First grant source_credentials the Service Account Token Creator role on the target account to impersonate. In this example, the service account represented by svc_account.json has the token creator role on impersonated-account@_project_.iam.gserviceaccount.com.

Enable the IAMCredentials API on the source project: gcloud services enable iamcredentials.googleapis.com.

Initialize a source credential which does not have access to list bucket:

from google.oauth2 import service_account

target_scopes = [
    'https://www.googleapis.com/auth/devstorage.read_only']

source_credentials = (
    service_account.Credentials.from_service_account_file(
        '/path/to/svc_account.json',
        scopes=target_scopes))

Now use the source credentials to acquire credentials to impersonate another service account:

from google.auth import impersonated_credentials

target_credentials = impersonated_credentials.Credentials(
  source_credentials=source_credentials,
  target_principal='impersonated-account@_project_.iam.gserviceaccount.com',
  target_scopes = target_scopes,
  lifetime=500)

Resource access is granted:

client = storage.Client(credentials=target_credentials)
buckets = client.list_buckets(project='your_project')
for bucket in buckets:
  print(bucket.name)
Parameters
  • source_credentials (google.auth.Credentials) – The source credential used as to acquire the impersonated credentials.

  • target_principal (str) – The service account to impersonate.

  • target_scopes (Sequencestr) – Scopes to request during the authorization grant.

  • delegates (Sequencestr) – The chained list of delegates required to grant the final access_token. If set, the sequence of identities must have “Service Account Token Creator” capability granted to the prceeding identity. For example, if set to [serviceAccountB, serviceAccountC], the source_credential must have the Token Creator role on serviceAccountB. serviceAccountB must have the Token Creator on serviceAccountC. Finally, C must have Token Creator on target_principal. If left unset, source_credential must have that role on target_principal.

  • lifetime (int) – Number of seconds the delegated credential should be valid for (upto 3600).

  • quota_project_id (Optionalstr) – The project ID used for quota and billing. This project may be different from the project used to create the credentials.

  • iam_endpoint_override (Optionalstr) – The full IAM endpoint override with the target_principal embedded. This is useful when supporting impersonation with regional endpoints.

  • subject (Optionalstr) – sub field of a JWT. This field should only be set if you wish to impersonate as a user. This feature is useful when using domain wide delegation.

expiry

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

Type

Optionaldatetime

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.

sign_bytes(message)[source]

Signs the given message.

Parameters

message (bytes) – The message to sign.

Returns

The message’s cryptographic signature.

Return type

bytes

property signer_email

An email address that identifies the signer.

Type

Optionalstr

property signer

The signer used to sign bytes.

Type

google.auth.crypt.Signer

property requires_scopes

True if these credentials require scopes to obtain an access token.

get_cred_info()[source]

The credential information JSON.

The credential information will be added to auth related error messages by client library.

Returns

The credential information JSON.

Return type

Mappingstr, str

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

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.

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.

class IDTokenCredentials(target_credentials, target_audience=None, include_email=False, quota_project_id=None)[source]

Bases: google.auth.credentials.CredentialsWithQuotaProject

Open ID Connect ID Token-based service account credentials.

Parameters
  • target_credentials (google.auth.Credentials) – The target credential used as to acquire the id tokens for.

  • target_audience (string) – Audience to issue the token for.

  • include_email (bool) – Include email in IdToken

  • quota_project_id (Optionalstr) – The project ID used for quota and billing.

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

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)

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)

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

get_cred_info()

The credential information JSON.

The credential information will be added to auth related error messages by client library.

Returns

The credential information JSON.

Return type

Mappingstr, str

property quota_project_id

Project to use for quota and billing purposes.

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.

expiry

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

Type

Optionaldatetime