google.oauth2.sts module

OAuth 2.0 Token Exchange Spec.

This module defines a token exchange utility based on the OAuth 2.0 Token Exchange spec. This will be mainly used to exchange external credentials for GCP access tokens in workload identity pools to access Google APIs.

The implementation will support various types of client authentication as allowed in the spec.

A deviation on the spec will be for additional Google specific options that cannot be easily mapped to parameters defined in the RFC.

The returned dictionary response will be based on the rfc8693 section 2.2.1 spec JSON response.

class Client(token_exchange_endpoint, client_authentication=None)[source]

Bases: OAuthClientAuthHandler

Implements the OAuth 2.0 token exchange spec based on https://tools.ietf.org/html/rfc8693.

Initializes an STS client instance.

Parameters:

  • token_exchange_endpoint (str) – The token exchange endpoint.

  • client_authentication (Optional(google.oauth2.oauth2_utils.ClientAuthentication)) – The optional OAuth client authentication credentials if available.

exchange_token(request, grant_type, subject_token, subject_token_type, resource=None, audience=None, scopes=None, requested_token_type=None, actor_token=None, actor_token_type=None, additional_options=None, additional_headers=None)[source]

Exchanges the provided token for another type of token based on the rfc8693 spec.

Parameters:

  • request (google.auth.transport.Request) – A callable used to make HTTP requests.

  • grant_type (str) – The OAuth 2.0 token exchange grant type.

  • subject_token (str) – The OAuth 2.0 token exchange subject token.

  • subject_token_type (str) – The OAuth 2.0 token exchange subject token type.

  • resource (Optional [ str ]) – The optional OAuth 2.0 token exchange resource field.

  • audience (Optional [ str ]) – The optional OAuth 2.0 token exchange audience field.

  • scopes (Optional [ Sequence [ str ] ]) – The optional list of scopes to use.

  • requested_token_type (Optional [ str ]) – The optional OAuth 2.0 token exchange requested token type.

  • actor_token (Optional [ str ]) – The optional OAuth 2.0 token exchange actor token.

  • actor_token_type (Optional [ str ]) – The optional OAuth 2.0 token exchange actor token type.

  • additional_options (Optional [ Mapping [ str, str ] ]) – The optional additional non-standard Google specific options.

  • additional_headers (Optional [ Mapping [ str, str ] ]) – The optional additional headers to pass to the token exchange endpoint.

Returns:

The token exchange JSON-decoded response data containing

the requested token and its expiration time.

Return type:

Mapping [ str, str ]

Raises:

google.auth.exceptions.OAuthError – If the token endpoint returned an error.

refresh_token(request, refresh_token)[source]

Exchanges a refresh token for an access token based on the RFC6749 spec.

Parameters:
apply_client_authentication_options(headers, request_body=None, bearer_token=None)

Applies client authentication on the OAuth request’s headers or POST body.

Parameters:

  • headers (Mapping [ str, str ]) – The HTTP request header.

  • request_body (Optional [ Mapping [ str, str ] ]) – The HTTP request body dictionary. For requests that do not support request body, this is None and will be ignored.

  • bearer_token (Optional [ str ]) – The optional bearer token.