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.

This module also provides a definition for an abstract AWS security credentials supplier. This supplier can be implemented to return valid AWS security credentials and an AWS region and used to create AWS credentials. The credentials will then call the supplier instead of using pre-defined methods such as calling the EC2 metadata endpoints.

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 (AWSSecurityCredentials) – 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 (Optionalstr) – The optional request payload if available.

  • additional_headers (OptionalMappingstr, str) – The optional additional headers needed for the requested AWS API.

Returns

The AWS signed request dictionary object.

Return type

Mappingstr, str

class AwsSecurityCredentials(access_key_id: str, secret_access_key: str, session_token: Optional[str] = None)[source]

Bases: object

A class that models AWS security credentials with an optional session token.

access_key_id

The AWS security credentials access key id.

Type

str

secret_access_key

The AWS security credentials secret access key.

Type

str

session_token

The optional AWS security credentials session token. This should be set when using temporary credentials.

Type

Optionalstr

class AwsSecurityCredentialsSupplier[source]

Bases: object

Base class for AWS security credential suppliers. This can be implemented with custom logic to retrieve AWS security credentials to exchange for a Google Cloud access token. The AWS external account credential does not cache the AWS security credentials, so caching logic should be added in the implementation.

abstract get_aws_security_credentials(context, request)[source]

Returns the AWS security credentials for the requested context.

Parameters
  • context (google.auth.externalaccount.SupplierContext) – The context object containing information about the requested audience and subject token type.

  • request (google.auth.transport.Request) – The object used to make HTTP requests.

Raises

google.auth.exceptions.RefreshError – If an error is encountered during security credential retrieval logic.

Returns

The requested AWS security credentials.

Return type

AwsSecurityCredentials

abstract get_aws_region(context, request)[source]

Returns the AWS region for the requested context.

Parameters
  • context (google.auth.externalaccount.SupplierContext) – The context object containing information about the requested audience and subject token type.

  • request (google.auth.transport.Request) – The object used to make HTTP requests.

Raises

google.auth.exceptions.RefreshError – If an error is encountered during region retrieval logic.

Returns

The AWS region.

Return type

str

class Credentials(audience, subject_token_type, token_url='https://sts.{universe_domain}/v1/token', credential_source=None, aws_security_credentials_supplier=None, *args, **kwargs)[source]

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

    “urn:ietf:params:aws:token-type:aws4_request”
    

  • token_url (Optional [str]) – The STS endpoint URL. If not provided, will default to “https://sts.googleapis.com/v1/token”.

  • credential_source (Optional [Mapping]) –

    The credential source dictionary used to provide instructions on how to retrieve external credential to be exchanged for Google access tokens. Either a credential source or an AWS security credentials supplier must be provided.

    Example credential_source for AWS credential:

    {
        "environment_id": "aws1",
        "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
        "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
        "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
        imdsv2_session_token_url": "http://169.254.169.254/latest/api/token"
    }
    

  • aws_security_credentials_supplier (Optional [AwsSecurityCredentialsSupplier]) – Optional AWS security credentials supplier. This will be called to supply valid AWS security credentails which will then be exchanged for Google access tokens. Either an AWS security credentials supplier or a credential source must be provided.

  • args (List) – Optional positional arguments passed into the underlying __init__() method.

  • kwargs (Mapping) – Optional keyword arguments passed into the underlying __init__() method.

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

str

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 an AWS Credentials instance from parsed external account info.

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

  • kwargs – Additional arguments to pass to the constructor.

Returns

The constructed credentials.

Return type

google.auth.aws.Credentials

Raises

ValueError – For invalid parameters.

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

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

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

Optionalstr

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

Sequencestr

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 token_info_url

The STS token introspection endpoint.

Type

Optionalstr

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.

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.

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

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

google.auth.aws.Credentials