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, lifetime=3600, quota_project_id=None, iam_endpoint_override=None)[source]¶
Bases:
Scoped
,CredentialsWithQuotaProject
,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 (
Sequence
[str
]) – Scopes to request during the authorization grant.delegates (
Sequence
[str
]) – 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 (
Optional
[str
]) – The project ID used for quota and billing. This project may be different from the project used to create the credentials.iam_endpoint_override (Optiona[str]) – The full IAM endpoint override with the target_principal embedded. This is useful when supporting impersonation with regional endpoints.
- expiry¶
When the token expires and is no longer valid. If this is None, the token is assumed to never expire.
- 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 signer¶
The signer used to sign bytes.
- Type:
- property requires_scopes¶
True if these credentials require scopes to obtain an access token.
- 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:
- 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.
- 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 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.
- property quota_project_id¶
Project to use for quota and billing purposes.
- class IDTokenCredentials(target_credentials, target_audience=None, include_email=False, quota_project_id=None)[source]¶
Bases:
CredentialsWithQuotaProject
Open ID Connect ID Token-based service account credentials.
- Parameters:
- apply(headers, token=None)¶
Apply the token to the authentication header.
- 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.
- property quota_project_id¶
Project to use for quota and billing purposes.
- property valid¶
Checks the validity of the credentials.
This is True if the credentials have a
token
and the token is notexpired
.
- 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:
- expiry¶
When the token expires and is no longer valid. If this is None, the token is assumed to never expire.
- 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.