google.auth.aws module¶
AWS Credentials and AWS Signature V4 Request Signer.
This module provides credentials to access Google Cloud resources from Amazon Web Services (AWS) workloads. These credentials are recommended over the use of service account credentials in AWS as they do not involve the management of long-live service account private keys.
AWS Credentials are initialized using external_account arguments which are typically loaded from the external credentials JSON file. 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.
This module also provides a basic implementation of the AWS Signature Version 4 request signing algorithm.
AWS Credentials use serialized signed requests to the AWS STS GetCallerIdentity API that can be exchanged for Google access tokens via the GCP STS endpoint.
- class RequestSigner(region_name)[source]¶
Bases:
object
Implements an AWS request signer based on the AWS Signature Version 4 signing process. https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
Instantiates an AWS request signer used to compute authenticated signed requests to AWS APIs based on the AWS Signature Version 4 signing process.
- Parameters:
region_name (str) – The AWS region to use.
- get_request_options(aws_security_credentials, url, method, request_payload='', additional_headers={})[source]¶
Generates the signed request for the provided HTTP request for calling an AWS API. This follows the steps described at: https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html
- Parameters:
aws_security_credentials (
Mapping
[str
,str
]) – A dictionary containing the AWS security credentials.url (str) – The AWS service URL containing the canonical URI and query string.
method (str) – The HTTP method used to call this API.
request_payload (
Optional
[str
]) – The optional request payload if available.additional_headers (
Optional
[Mapping
[str
,str
] ]) – The optional additional headers needed for the requested AWS API.
- Returns:
The AWS signed request dictionary object.
- Return type:
- class Credentials(audience, subject_token_type, token_url, credential_source=None, service_account_impersonation_url=None, client_id=None, client_secret=None, quota_project_id=None, scopes=None, default_scopes=None)[source]¶
Bases:
Credentials
AWS external account credentials. This is used to exchange serialized AWS signature v4 signed requests to AWS STS GetCallerIdentity service for Google access tokens.
Instantiates an AWS workload 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 used to provide instructions on how to retrieve external credential to be exchanged for Google access tokens.
service_account_impersonation_url (
Optional
[str
]) – The optional service account impersonation getAccessToken URL.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 an error is encountered during access token retrieval logic.
ValueError – For invalid parameters.
Note
Typically one of the helper constructors
from_file()
orfrom_info()
are used instead of calling the constructor directly.- retrieve_subject_token(request)[source]¶
Retrieves the subject token using the credential_source object. The subject token is a serialized AWS GetCallerIdentity signed request.
The logic is summarized as:
Retrieve the AWS region from the AWS_REGION or AWS_DEFAULT_REGION environment variable or from the AWS metadata server availability-zone if not found in the environment variable.
Check AWS credentials in environment variables. If not found, retrieve from the AWS metadata server security-credentials endpoint.
When retrieving AWS credentials from the metadata server security-credentials endpoint, the AWS role needs to be determined by calling the security-credentials endpoint without any argument. Then the credentials can be retrieved via: security-credentials/role_name
Generate the signed request to AWS STS GetCallerIdentity action.
Inject x-goog-cloud-target-resource into header and serialize the signed request. This will be the subject-token to pass to GCP STS.
- Parameters:
request (google.auth.transport.Request) – A callable used to make HTTP requests.
- Returns:
The retrieved subject token.
- Return type:
- classmethod from_info(info, **kwargs)[source]¶
Creates an AWS Credentials instance from parsed external account info.
- Parameters:
- Returns:
The constructed credentials.
- Return type:
- Raises:
ValueError – For invalid parameters.
- classmethod from_file(filename, **kwargs)[source]¶
Creates an AWS Credentials instance from an external account json file.
- Parameters:
filename (str) – The path to the AWS external account json file.
kwargs – Additional arguments to pass to the constructor.
- Returns:
The constructed credentials.
- Return type:
- 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.
- 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:
- has_scopes(scopes)¶
Checks if the credentials have the given scopes.
- 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:
- static is_valid_url(patterns, url)[source]¶
Returns True if the provided URL’s scheme is HTTPS and the host comforms to at least one of the provided patterns.
- 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:
- property project_number¶
The project number corresponding to the workload identity pool.
- 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:
- property service_account_email¶
Returns the service account email if service account impersonation is used.
- 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:
- 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.