docs: add documentation for suppliers

docs/user-guide.rst

@@ -212,7 +212,7 @@ There is a separate library, `google-auth-oauthlib`_, that has some helpers
 for integrating with `requests-oauthlib`_ to provide support for obtaining
 user credentials. You can use
 :func:`google_auth_oauthlib.helpers.credentials_from_session` to obtain
-:class:`google.oauth2.credentials.Credentials` from a 
+:class:`google.oauth2.credentials.Credentials` from a
 :class:`requests_oauthlib.OAuth2Session` as above::
 
     from google_auth_oauthlib.helpers import credentials_from_session
@@ -459,9 +459,9 @@ Error responses must include both the ``code`` and ``message`` fields.
 
 The library will populate the following environment variables when the
 executable is run: ``GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE``: The audience
-field from the credential configuration. Always present. 
+field from the credential configuration. Always present.
 ``GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL``: The service account
-email. Only present when service account impersonation is used. 
+email. Only present when service account impersonation is used.
 ``GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE``: The output file location from
 the credential configuration. Only present when specified in the
 credential configuration.
@@ -486,6 +486,91 @@ they do not meet your specific requirements.
 You can now `use the Auth library <#using-external-identities>`__ to
 call Google Cloud resources from an OIDC or SAML provider.
 
+
+Accessing resources using a custom supplier with OIDC or SAML
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This library also allows for a custom implementation of :class:`google.auth.identity_pool.SubjectTokenSupplier`
+to be specificed when creating a :class:`google.auth.identity_pool.Credential`. The supplier must
+return a valid OIDC or SAML2.0 subject token, which will then be exchanged for a
+Google Cloud access token.::
+
+    from google.auth import identity_pool
+
+    class CustomSubjectTokenSupplier(identity_pool.SubjectTokenSupplier):
+
+        def get_subject_token(self, context, request):
+            audience = context.audience
+            subject_token_type = context.subject_token_type
+            # Return a valid subject token of the requested type for the requested audience.
+
+    supplier = CustomSubjectTokenSupplier()
+
+    credentials = identity_pool.Credentials(
+        AUDIENCE, # Set GCP Audience.
+        "urn:ietf:params:aws:token-type:jwt", # Set subject token type.
+        subject_token_supplier=supplier, # Set supplier.
+        scopes=SCOPES # Set desired scopes.
+    )
+
+Where the `audience`_ is: ``//iam.googleapis.com/locations/global/workloadPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID``
+Where the following variables need to be substituted:
+
+* ``$WORKLOAD_POOL_ID``: The workload pool ID.
+* ``$PROVIDER_ID``: The provider ID.
+
+The values for audience, service account impersonation URL, and any other builder field can also be found
+by generating a `credential configuration file with the gcloud CLI`_.
+
+.. _audience:
+    https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience
+.. _credential configuration file with the gcloud CLI:
+    https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config
+
+Accessing resources using a custom supplier with AWS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This library also allows for a custom implementation of :class:`google.auth.aws.AwsSecurityCredentialsSupplier`
+to be specificed when creating a :class:`google.auth.aws.Credential`. The supplier must
+return valid AWS security credentials, which will then be exchanged for a
+Google Cloud access token.::
+
+    from google.auth import aws
+
+    class CustomAwsSecurityCredentialsSupplier(aws.AwsSecurityCredentialsSupplier):
+
+        def get_aws_security_credentials(self, context, request):
+            audience = context.audience
+            # Return valid AWS security credentials. These credentials are not cached by
+            # the google credential, so caching should be implemented in the supplier.
+            return aws.AwsSecurityCredentials(ACCESS_KEY_ID, SECRET_ACCESS_KEY, SESSION_TOKEN)
+
+        def get_aws_region(self, context, request):
+            # Return active AWS region.
+
+    supplier = CustomAwsSecurityCredentialsSupplier()
+
+    credentials = aws.Credentials(
+        AUDIENCE, # Set GCP Audience.
+        "urn:ietf:params:aws:token-type:aws4_request", # Set AWS subject token type.
+        aws_security_token_supplier=supplier, # Set supplier.
+        scopes=SCOPES # Set desired scopes.
+    )
+
+Where the `audience`_ is: ``//iam.googleapis.com/locations/global/workloadPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID``
+Where the following variables need to be substituted:
+
+* ``$WORKLOAD_POOL_ID``: The workload pool ID.
+* ``$PROVIDER_ID``: The provider ID.
+
+The values for audience, service account impersonation URL, and any other builder field can also be found
+by generating a `credential configuration file with the gcloud CLI`_.
+
+.. _audience:
+    https://cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation#provider-audience
+.. _credential configuration file with the gcloud CLI:
+    https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config
+
 Using External Identities
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -774,6 +859,49 @@ Refer to the `using executable-sourced credentials with Workload Identity
 Federation <Using-Executable-sourced-credentials-with-OIDC-and-SAML>`__ above
 for the executable response specification.
 
+Accessing resources using a custom supplier with OIDC or SAML
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This library also allows for a custom implementation of :class:`google.auth.identity_pool.SubjectTokenSupplier`
+to be specificed when creating a :class:`google.auth.identity_pool.Credential`. The supplier must
+return a valid OIDC or SAML2.0 subject token, which will then be exchanged for a
+Google Cloud access token.::
+
+    from google.auth import identity_pool
+
+    class CustomSubjectTokenSupplier(identity_pool.SubjectTokenSupplier):
+
+        def get_subject_token(self, context, request):
+            audience = context.audience
+            subject_token_type = context.subject_token_type
+            # Return a valid subject token of the requested type for the requested audience.
+
+    supplier = CustomSubjectTokenSupplier()
+
+    credentials = identity_pool.Credentials(
+        AUDIENCE, # Set GCP Audience.
+        "urn:ietf:params:aws:token-type:jwt", # Set subject token type.
+        subject_token_supplier=supplier, # Set supplier.
+        scopes=SCOPES, # Set desired scopes.
+        workforce_pool_user_project=USER_PROJECT # Set workforce pool user project.
+    )
+
+Where the audience is: ``//iam.googleapis.com/locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID``
+Where the following variables need to be substituted:
+
+* ``$WORKFORCE_POOL_ID``: The workforce pool ID.
+* ``$PROVIDER_ID``: The provider ID.
+
+and the workforce pool user project is the project number associated with the `workforce pools user project`_.
+
+The values for audience, service account impersonation URL, and any other builder field can also be found
+by generating a `credential configuration file`_ with the gcloud CLI.
+
+.. _workforce pools user project:
+    https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project
+.. _credential configuration file:
+    https://cloud.google.com/iam/docs/workforce-obtaining-short-lived-credentials#use_configuration_files_for_sign-in
+
 Security considerations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -814,7 +942,7 @@ Impersonated credentials
 ++++++++++++++++++++++++
 
 Impersonated Credentials allows one set of credentials issued to a user or service account
-to impersonate another. The source credentials must be granted 
+to impersonate another. The source credentials must be granted
 the "Service Account Token Creator" IAM role. ::
 
     from google.auth import impersonated_credentials
@@ -884,7 +1012,7 @@ Token broker ::
     credential_access_boundary = downscoped.CredentialAccessBoundary(
         rules=[rule])
 
-    # Retrieve the source credentials via ADC. 
+    # Retrieve the source credentials via ADC.
     source_credentials, _ = google.auth.default()
 
     # Create the downscoped credentials.

google/auth/aws.py

@@ -21,10 +21,11 @@
 
 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 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.

google/auth/identity_pool.py

@@ -26,11 +26,13 @@
 
 Identity Pool Credentials are initialized using external_account
 arguments which are typically loaded from an external credentials file or
-an external credentials URL. 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.
+an external credentials URL.
+
+This module also provides a definition for an abstract subject token supplier.
+This supplier can be implemented to return a valid OIDC or SAML2.0 subject token
+and used to create Identity Pool credentials. The credentials will then call the
+supplier instead of using pre-defined methods such as reading a local file or
+calling a URL.
 """
 
 try: