From 0f7d08531ebc6302f4f02445ceaeff8e9f00c7eb Mon Sep 17 00:00:00 2001 From: aeitzman Date: Wed, 13 Mar 2024 11:00:40 -0700 Subject: [PATCH 1/3] docs: update docs for programmatic --- google/auth/aws.py | 9 +++++---- google/auth/identity_pool.py | 12 +++++++----- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/google/auth/aws.py b/google/auth/aws.py index a3f497442..5a61aa66a 100644 --- a/google/auth/aws.py +++ b/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. diff --git a/google/auth/identity_pool.py b/google/auth/identity_pool.py index 77bc7735b..caddda3e4 100644 --- a/google/auth/identity_pool.py +++ b/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: From 052ab4284ac134a9b5a690e17fdc27568e50ef22 Mon Sep 17 00:00:00 2001 From: aeitzman Date: Wed, 13 Mar 2024 11:16:41 -0700 Subject: [PATCH 2/3] add space --- google/auth/aws.py | 2 +- google/auth/identity_pool.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/google/auth/aws.py b/google/auth/aws.py index 5a61aa66a..ffa65476c 100644 --- a/google/auth/aws.py +++ b/google/auth/aws.py @@ -24,7 +24,7 @@ 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 +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 diff --git a/google/auth/identity_pool.py b/google/auth/identity_pool.py index caddda3e4..4f2a14367 100644 --- a/google/auth/identity_pool.py +++ b/google/auth/identity_pool.py @@ -30,7 +30,7 @@ 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 +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. """ From 62ac988f1de3817c32f7b895ae02a8194193c2ce Mon Sep 17 00:00:00 2001 From: aeitzman Date: Thu, 14 Mar 2024 09:29:52 -0700 Subject: [PATCH 3/3] update user guide --- docs/user-guide.rst | 138 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 133 insertions(+), 5 deletions(-) diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 0cb119127..22224c2d9 100644 --- a/docs/user-guide.rst +++ b/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 `__ 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.