Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified	Actions
📁 ..	-	2025-06-25 08:26
📁 _static	-	2025-04-14 17:36
📄 conf.py #!/usr/bin/env python3 # -- coding: utf-8 -- # # google-auth documentation build configuration file, created by # sphinx-quickstart on Thu Sep 22 12:50:15 2016. # # This file is execfile()d with the current directory set to its # containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import google.auth # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # # import os # import sys # sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. # # needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.') or your custom # ones. extensions = [ "sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", "sphinx.ext.napoleon", "sphinx_docstring_typing", ] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = ".rst" # The encoding of source files. # # source_encoding = 'utf-8-sig' # The root toctree document. root_doc = "index" # General information about the project. project = "google-auth" copyright = "2016, Google, Inc." author = "Google, Inc." # The version info for the project you're documenting, acts as replacement for # \|version\| and \|release\|, also used in various other places throughout the # built documents. # # The short X.Y version. version = google.auth.__version__ # The full version, including alpha/beta/rc tags. release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = "en" # There are two options for replacing \|today\|: either, you set today to some # non-false value, then it is used: # # today = '' # # Else, today_fmt is used as the format for a strftime call. # # today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # The reST default role (used for this markup: `text`) to use for all # documents. # # default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. # # add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). # add_module_names = False # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. # # show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. # keep_warnings = False # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = "alabaster" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # html_theme_options = { "description": "Google Auth Library for Python", "github_user": "GoogleCloudPlatform", "github_repo": "google-auth-library-python", "github_banner": True, "travis_button": True, "font_family": "'Roboto', Georgia, sans", "head_font_family": "'Roboto', Georgia, serif", "code_font_family": "'Roboto Mono', 'Consolas', monospace", } # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] # The name for this set of Sphinx documents. # "<project> v<release> documentation" by default. # # html_title = 'google-auth v0.0.1a' # A shorter title for the navigation bar. Default is the same as html_title. # # html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. # # html_logo = None # The name of an image file (relative to this directory) to use as a favicon of # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. # # html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. # # html_extra_path = [] # If not None, a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. # The empty string is equivalent to '%b %d, %Y'. # # html_last_updated_fmt = None # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. # # html_use_smartypants = True # Custom sidebar templates, maps document names to template names. # html_sidebars = { "*": ["about.html", "navigation.html", "relations.html", "searchbox.html"] } # Additional templates that should be rendered to pages, maps page names to # template names. # # html_additional_pages = {} # If false, no module index is generated. # # html_domain_indices = True # If false, no index is generated. # # html_use_index = True # If true, the index is split into individual pages for each letter. # # html_split_index = False # If true, links to the reST sources are added to the pages. # # html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. # # html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. # # html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a <link> tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. # # html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). # html_file_suffix = None # Language to be used for generating the HTML full-text search index. # Sphinx supports the following languages: # 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' # 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' # # html_search_language = 'en' # A dictionary with options for the search language support, empty by default. # 'ja' uses this config value. # 'zh' user can custom change `jieba` dictionary path. # # html_search_options = {'type': 'default'} # The name of a javascript file (relative to the configuration directory) that # implements a search results scorer. If empty, the default will be used. # # html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. htmlhelp_basename = "google-authdoc" # -- Options for LaTeX output --------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # # 'preamble': '', # Latex figure (float) alignment # # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (root_doc, "google-auth.tex", "google-auth Documentation", "Google, Inc.", "manual") ] # The name of an image file (relative to this directory) to place at the top of # the title page. # # latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. # # latex_use_parts = False # If true, show page references after internal links. # # latex_show_pagerefs = False # If true, show URL addresses after external links. # # latex_show_urls = False # Documents to append as an appendix to all manuals. # # latex_appendices = [] # It false, will not define \strong, \code, itleref, \crossref ... but only # \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added # packages. # # latex_keep_old_macro_names = True # If false, no module index is generated. # # latex_domain_indices = True # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [(root_doc, "google-auth", "google-auth Documentation", [author], 1)] # If true, show URL addresses after external links. # # man_show_urls = False # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ ( root_doc, "google-auth", "google-auth Documentation", author, "google-auth", "One line description of project.", "Miscellaneous", ) ] # Documents to append as an appendix to all manuals. # # texinfo_appendices = [] # If false, no module index is generated. # # texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. # # texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. # # texinfo_no_detailmenu = False # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://docs.python.org/3.5", None), "urllib3": ("https://urllib3.readthedocs.io/en/stable", None), "requests": ("https://requests.kennethreitz.org/en/master/", None), "requests-oauthlib": ( "https://requests-oauthlib.readthedocs.io/en/v1.3.0-docs/", None, ), } # Autodoc config autoclass_content = "both" autodoc_member_order = "bysource" autodoc_mock_imports = ["grpc"]	10.72 KB	2025-04-14 17:36
📄 index.rst google-auth =========== .. toctree:: :hidden: :maxdepth: 2 user-guide Reference <reference/modules> google-auth is the Google authentication library for Python. This library provides the ability to authenticate to Google APIs using various methods. It also provides integration with several HTTP libraries. - Support for Google :func:`Application Default Credentials <google.auth.default>`. - Support for signing and verifying :mod:`JWTs <google.auth.jwt>`. - Support for creating `Google ID Tokens <user-guide.html#identity-tokens>`__. - Support for verifying and decoding :mod:`ID Tokens <google.oauth2.id_token>`. - Support for Google :mod:`Service Account credentials <google.oauth2.service_account>`. - Support for Google :mod:`Impersonated Credentials <google.auth.impersonated_credentials>`. - Support for :mod:`Google Compute Engine credentials <google.auth.compute_engine>`. - Support for :mod:`Google App Engine standard credentials <google.auth.app_engine>`. - Support for :mod:`Identity Pool credentials <google.auth.identity_pool>`. - Support for :mod:`AWS credentials <google.auth.aws>`. - Support for :mod:`Downscoping with Credential Access Boundaries credentials <google.auth.downscoped>`. - Support for various transports, including :mod:`Requests <google.auth.transport.requests>`, :mod:`urllib3 <google.auth.transport.urllib3>`, and :mod:`gRPC <google.auth.transport.grpc>`. .. note:: ``oauth2client`` was recently deprecated in favor of this library. For more details on the deprecation, see :doc:`oauth2client-deprecation`. Installing ---------- google-auth can be installed with `pip`_:: $ pip install --upgrade google-auth google-auth is open-source, so you can alternatively grab the source code from `GitHub`_ and install from source. For more information on setting up your Python development environment, please refer to `Python Development Environment Setup Guide`_ for Google Cloud Platform. .. _`Python Development Environment Setup Guide`: https://cloud.google.com/python/setup .. _pip: https://pip.pypa.io .. _GitHub: https://github.com/GoogleCloudPlatform/google-auth-library-python Usage ----- The :doc:`user-guide` is the place to go to learn how to use the library and accomplish common tasks. The :doc:`Module Reference <reference/modules>` documentation provides API-level documentation. License ------- google-auth is made available under the Apache License, Version 2.0. For more details, see `LICENSE`_ .. _LICENSE: https://github.com/GoogleCloudPlatform/google-auth-library-python/blob/main/LICENSE Contributing ------------ We happily welcome contributions, please see our `contributing`_ documentation for details. .. _contributing: https://github.com/GoogleCloudPlatform/google-auth-library-python/blob/main/CONTRIBUTING.rst	2.76 KB	2025-04-14 17:36
📄 oauth2client-deprecation.rst :orphan: oauth2client deprecation ======================== This page is intended for existing users of the `oauth2client`_ who want to understand the reasons for its deprecation and how this library relates to ``oauth2client``. .. _oauth2client: https://github.com/google/oauth2client Reasons for deprecation ----------------------- #. Lack of ownership: ``oauth2client`` has lacked a definitive owner since around 2013. #. Fragile and ad-hoc design: ``oauth2client`` is the result of several years of ad-hoc additions and organic, uncontrolled growth. This has led to a library that lacks overall design and cohesion. The convoluted class hierarchy is a symptom of this. #. Lack of a secure, thread-safe, and modern transport: ``oauth2client`` is inextricably dependent on `httplib2`_. ``httplib2`` is largely unmaintained (although recently there are a small group of volunteers attempting to maintain it). #. Lack of clear purpose and goals: The library is named "oauth2client" but is actually a pretty poor OAuth 2.0 client and does a lot of things that have nothing to do with OAuth and its related RFCs. .. _httplib2: https://github.com/httplib2/httplib2 We originally planned to address these issues within ``oauth2client``, however, we determined that the number of breaking changes needed would be absolutely untenable for downstream users. It would essentially involve our users having to rewrite significant portions of their code if they needed to upgrade (either directly or indirectly through a dependency). Instead, we've chosen to create a new replacement library that can live side-by-side with ``oauth2client`` and allow users to migrate gradually. We believe that this was the least painful option. Replacement ----------- The long-term replacement for ``oauth2client`` is this library, ``google-auth``. This library addresses the major issues with oauthclient: #. Clear ownership: google-auth is owned by the teams that maintain the `Cloud Client Libraries`_, `gRPC`_, and the `Code Samples for Google Cloud Platform`_. #. Thought-out design: using the lessons learned from ``oauth2client``, we have designed a better module and class hierarchy. The ``v1.0.0`` release of this library should provide long-term API stability. #. Modern, secure, and extensible transports: ``google-auth`` supports `urllib3`_, `requests`_, `gRPC`_, and has `legacy support for httplib2`_ to help clients migration. It is transport agnostic and has explicit support for adding new transports. #. Clear purpose and goals: ``google-auth`` is explicitly focused on Google-specific authentication, especially the server-to-server (service account) use case. Because we reduced the scope of the library, there are several features in ``oauth2client`` we intentionally are not supporting in the ``v1.0.0`` release of ``google-auth``. This does not mean we are not interested in supporting these features, we just didn't feel they should be part of the initial API. As downstream users ask for these features we will determine the best way to serve those use cases without allowing the library to become a dumping ground. The unsupported features are: #. Support for obtaining user credentials. While this library has support for using user credentials, there are no provisions in the core library for doing the three-party OAuth 2.0 flow to obtain authorization from a user. Instead, we are opting to provide a separate package that does integration with `oauthlib`_, `google-auth-oauthlib`_. When that library has a stable API, we will consider its inclusion into the core library. #. Support for storing credentials. The only credentials type that needs to be stored are user credentials. We have a `discussion thread`_ on what level of support we should do. It's very likely we'll choose to provide an abstract interface for this and leave it up to application to provide storage implementation specific to their use case. It's also very likely that we will also incubate this functionality in the `google-auth-oauthlib`_ library before including it in the core library. .. _Cloud Client Libraries: https://github.com/googlecloudplatform/google-cloud-python .. _gRPC: http://www.grpc.io/ .. _Code Samples for Google Cloud Platform: https://github.com/googlecloudplatform/python-docs-samples .. _urllib3: https://urllib3.readthedocs.io .. _requests: http://python-requests.org .. _legacy support for httplib2: https://pypi.python.org/pypi/google-auth-httplib2 .. _oauthlib: https://oauthlib.readthedocs.io .. _google-auth-oauthlib: http://google-auth-oauthlib.readthedocs.io/ .. _discussion thread: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues/33 Post-deprecation support ------------------------ While ``oauth2client`` will not be implementing or accepting any new features, the ``google-auth`` team will continue to accept bug reports and fix critical bugs. We will make patch releases as necessary. We have no plans to remove the library from GitHub or PyPI. Also, we have made sure that the `google-api-python-client`_ library supports oauth2client and google-auth and will continue to do so indefinitely. It is important to note that we will not be adding any features, even if an external user goes through the trouble of sending a pull request. This policy is in place because without it we will perpetuate the circumstances that led to ``oauth2client`` being in the semi-unmaintained state it was in previously. Some old documentation and examples may use ``oauth2client`` instead of ``google-auth``. We are working to update all of these but it does take a significant amount of time. Since we are still iterating on user auth, some samples that use user auth will not be updated until we have settled on a final interface. If you find any samples you feel should be updated, please `file a bug`_. .. _google-api-python-client: https://github.com/google/google-api-python-client .. _file a bug: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues	5.97 KB	2025-04-14 17:36
📁 reference	-	2025-04-14 17:36
📄 requirements-docs.txt cryptography sphinx-docstring-typing urllib3 requests requests-oauthlib # We need to pin to specific versions of the `sphinxcontrib-*` packages # which still support sphinx 4.x. # See https://github.com/googleapis/sphinx-docfx-yaml/issues/344 # and https://github.com/googleapis/sphinx-docfx-yaml/issues/345. sphinxcontrib-applehelp==1.0.4 sphinxcontrib-devhelp==1.0.2 sphinxcontrib-htmlhelp==2.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.5 sphinx==4.5.0 alabaster recommonmark	501 B	2025-04-14 17:36
📄 user-guide.rst User Guide ========== .. currentmodule:: google.auth Credentials and account types ----------------------------- :class:`~credentials.Credentials` are the means of identifying an application or user to a service or API. Credentials can be obtained with three different types of accounts: service accounts, user accounts and external accounts. Credentials from service accounts identify a particular application. These types of credentials are used in server-to-server use cases, such as accessing a database. This library primarily focuses on service account credentials. Credentials from user accounts are obtained by asking the user to authorize access to their data. These types of credentials are used in cases where your application needs access to a user's data in another service, such as accessing a user's documents in Google Drive. This library provides no support for obtaining user credentials, but does provide limited support for using user credentials. Credentials from external accounts (workload identity federation) are used to identify a particular application from an on-prem or non-Google Cloud platform including Amazon Web Services (AWS), Microsoft Azure or any identity provider that supports OpenID Connect (OIDC). Obtaining credentials --------------------- .. warning:: Important: If you accept a credential configuration (credential JSON/File/Stream) from an external source for authentication to Google Cloud Platform, you must validate it before providing it to any Google API or client library. Providing an unvalidated credential configuration to Google APIs or libraries can compromise the security of your systems and data. For more information, refer to `Validate credential configurations from external sources`_. .. _Validate credential configurations from external sources: https://cloud.google.com/docs/authentication/external/externally-sourced-credentials .. _application-default: Application default credentials +++++++++++++++++++++++++++++++ `Google Application Default Credentials`_ abstracts authentication across the different Google Cloud Platform hosting environments. When running on any Google Cloud hosting environment or when running locally with the `Google Cloud SDK`_ installed, :func:`default` can automatically determine the credentials from the environment:: import google.auth credentials, project = google.auth.default() If your application requires specific scopes:: credentials, project = google.auth.default( scopes=['https://www.googleapis.com/auth/cloud-platform']) Application Default Credentials also support workload identity federation to access Google Cloud resources from non-Google Cloud platforms including Amazon Web Services (AWS), Microsoft Azure or any identity provider that supports OpenID Connect (OIDC). Workload identity federation is recommended for non-Google Cloud environments as it avoids the need to download, manage and store service account private keys locally. .. _Google Application Default Credentials: https://developers.google.com/identity/protocols/ application-default-credentials .. _Google Cloud SDK: https://cloud.google.com/sdk Compute Engine, Container Engine, and the App Engine flexible environment +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Applications running on `Compute Engine`_, `Container Engine`_, or the `App Engine flexible environment`_ can obtain credentials provided by `Compute Engine service accounts`_. When running on these platforms you can obtain credentials for the service account one of two ways: 1. Use :ref:`application default credentials <application-default>`. :func:`default` will automatically detect if these credentials are available. 2. Use :class:`compute_engine.Credentials`:: from google.auth import compute_engine credentials = compute_engine.Credentials() .. _Compute Engine: https://cloud.google.com/compute .. _Container Engine: https://cloud.google.com/container-engine .. _App Engine flexible environment: https://cloud.google.com/appengine/docs/flexible/ .. _Compute Engine service accounts: https://cloud.google.com/compute/docs/access/service-accounts The App Engine standard environment +++++++++++++++++++++++++++++++++++ Applications running on the `App Engine standard environment`_ can obtain credentials provided by the `App Engine App Identity API`_. You can obtain credentials one of two ways: 1. Use :ref:`application default credentials <application-default>`. :func:`default` will automatically detect if these credentials are available. 2. Use :class:`app_engine.Credentials`:: from google.auth import app_engine credentials = app_engine.Credentials() In order to make authenticated requests in the App Engine environment using the credentials and transports provided by this library, you need to follow a few additional steps: #. If you are using the :mod:`google.auth.transport.requests` transport, vendor in the `requests-toolbelt`_ library into your app, and enable the App Engine monkeypatch. Refer `App Engine documentation`_ for more details on this. #. To make HTTPS calls, enable the ``ssl`` library for your app by adding the following configuration to the ``app.yaml`` file:: libraries: - name: ssl version: latest #. Enable billing for your App Engine project. Then enable socket support for your app. This can be achieved by setting an environment variable in the ``app.yaml`` file:: env_variables: GAE_USE_SOCKETS_HTTPLIB : 'true' .. _App Engine standard environment: https://cloud.google.com/appengine/docs/python .. _App Engine App Identity API: https://cloud.google.com/appengine/docs/python/appidentity/ .. _requests-toolbelt: https://toolbelt.readthedocs.io/en/latest/ .. _App Engine documentation: https://cloud.google.com/appengine/docs/standard/python/issue-requests User credentials ++++++++++++++++ User credentials are typically obtained via `OAuth 2.0`_. This library does not provide any direct support for obtaining user credentials, however, you can use user credentials with this library. You can use libraries such as `oauthlib`_ to obtain the access token. After you have an access token, you can create a :class:`google.oauth2.credentials.Credentials` instance:: import google.oauth2.credentials credentials = google.oauth2.credentials.Credentials( 'access_token') If you obtain a refresh token, you can also specify the refresh token and token URI to allow the credentials to be automatically refreshed:: credentials = google.oauth2.credentials.Credentials( 'access_token', refresh_token='refresh_token', token_uri='token_uri', client_id='client_id', client_secret='client_secret') 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:`requests_oauthlib.OAuth2Session` as above:: from google_auth_oauthlib.helpers import credentials_from_session google_auth_credentials = credentials_from_session(oauth2session) You can also use :class:`google_auth_oauthlib.flow.Flow` to perform the OAuth 2.0 Authorization Grant Flow to obtain credentials using `requests-oauthlib`_. .. _OAuth 2.0: https://developers.google.com/identity/protocols/OAuth2 .. _oauthlib: https://oauthlib.readthedocs.io/en/latest/ .. _google-auth-oauthlib: https://pypi.python.org/pypi/google-auth-oauthlib .. _requests-oauthlib: https://requests-oauthlib.readthedocs.io/en/latest/ External credentials (Workload identity federation) +++++++++++++++++++++++++++++++++++++++++++++++++++ Using workload identity federation, your application can access Google Cloud resources from Amazon Web Services (AWS), Microsoft Azure or any identity provider that supports OpenID Connect (OIDC). Traditionally, applications running outside Google Cloud have used service account keys to access Google Cloud resources. Using identity federation, you can allow your workload to impersonate a service account. This lets you access Google Cloud resources directly, eliminating the maintenance and security burden associated with service account keys. Accessing resources from AWS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed: - A workload identity pool needs to be created. - AWS needs to be added as an identity provider in the workload identity pool (The Google organization policy needs to allow federation from AWS). - Permission to impersonate a service account needs to be granted to the external identity. - A credential configuration file needs to be generated. Unlike service account credential files, the generated credential configuration file will only contain non-sensitive metadata to instruct the library on how to retrieve external subject tokens and exchange them for service account access tokens. - If you want to use IDMSv2, then below field needs to be added to credential_source section of credential configuration. "imdsv2_session_token_url": "http://169.254.169.254/latest/api/token" Follow the detailed instructions on how to `Configure Workload Identity Federation from AWS`_. .. _Configure Workload Identity Federation from AWS: https://cloud.google.com/iam/docs/access-resources-aws Accessing resources from Microsoft Azure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to access Google Cloud resources from Microsoft Azure, the following requirements are needed: - A workload identity pool needs to be created. - Azure needs to be added as an identity provider in the workload identity pool (The Google organization policy needs to allow federation from Azure). - The Azure tenant needs to be configured for identity federation. - Permission to impersonate a service account needs to be granted to the external identity. - A credential configuration file needs to be generated. Unlike service account credential files, the generated credential configuration file will only contain non-sensitive metadata to instruct the library on how to retrieve external subject tokens and exchange them for service account access tokens. Follow the detailed instructions on how to `Configure Workload Identity Federation from Microsoft Azure`_. .. _Configure Workload Identity Federation from Microsoft Azure: https://cloud.google.com/iam/docs/access-resources-azure Accessing resources from an OIDC identity provider ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to access Google Cloud resources from an identity provider that supports `OpenID Connect (OIDC)`_, the following requirements are needed: - A workload identity pool needs to be created. - An OIDC identity provider needs to be added in the workload identity pool (The Google organization policy needs to allow federation from the identity provider). - Permission to impersonate a service account needs to be granted to the external identity. - A credential configuration file needs to be generated. Unlike service account credential files, the generated credential configuration file will only contain non-sensitive metadata to instruct the library on how to retrieve external subject tokens and exchange them for service account access tokens. For OIDC providers, the Auth library can retrieve OIDC tokens either from a local file location (file-sourced credentials) or from a local server (URL-sourced credentials). - For file-sourced credentials, a background process needs to be continuously refreshing the file location with a new OIDC token prior to expiration. For tokens with one hour lifetimes, the token needs to be updated in the file every hour. The token can be stored directly as plain text or in JSON format. - For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC token. The response can be in plain text or JSON. Additional required request headers can also be specified. Follow the detailed instructions on how to `Configure Workload Identity Federation from an OIDC identity provider`_. .. _OpenID Connect (OIDC): https://openid.net/connect/ .. _Configure Workload Identity Federation from an OIDC identity provider: https://cloud.google.com/iam/docs/access-resources-oidc Using Executable-sourced credentials with OIDC and SAML ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Executable-sourced credentials For executable-sourced credentials, a local executable is used to retrieve the 3rd party token. The executable must handle providing a valid, unexpired OIDC ID token or SAML assertion in JSON format to stdout. To use executable-sourced credentials, the ``GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES`` environment variable must be set to ``1``. To generate an executable-sourced workload identity configuration, run the following command: .. code:: bash # Generate a configuration file for executable-sourced credentials. gcloud iam workload-identity-pools create-cred-config \ projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID \ --service-account=$SERVICE_ACCOUNT_EMAIL \ --subject-token-type=$SUBJECT_TOKEN_TYPE \ # The absolute path for the program, including arguments. # e.g. --executable-command="/path/to/command --foo=bar" --executable-command=$EXECUTABLE_COMMAND \ # Optional argument for the executable timeout. Defaults to 30s. # --executable-timeout-millis=$EXECUTABLE_TIMEOUT \ # Optional argument for the absolute path to the executable output file. # See below on how this argument impacts the library behaviour. # --executable-output-file=$EXECUTABLE_OUTPUT_FILE \ --output-file /path/to/generated/config.json Where the following variables need to be substituted: - ``$PROJECT_NUMBER``: The Google Cloud project number. - ``$POOL_ID``: The workload identity pool ID. - ``$PROVIDER_ID``: The OIDC or SAML provider ID. - ``$SERVICE_ACCOUNT_EMAIL``: The email of the service account to impersonate. - ``$SUBJECT_TOKEN_TYPE``: The subject token type. - ``$EXECUTABLE_COMMAND``: The full command to run, including arguments. Must be an absolute path to the program. The ``--executable-timeout-millis`` flag is optional. This is the duration for which the auth library will wait for the executable to finish, in milliseconds. Defaults to 30 seconds when not provided. The maximum allowed value is 2 minutes. The minimum is 5 seconds. The ``--executable-output-file`` flag is optional. If provided, the file path must point to the 3PI credential response generated by the executable. This is useful for caching the credentials. By specifying this path, the Auth libraries will first check for its existence before running the executable. By caching the executable JSON response to this file, it improves performance as it avoids the need to run the executable until the cached credentials in the output file are expired. The executable must handle writing to this file - the auth libraries will only attempt to read from this location. The format of contents in the file should match the JSON format expected by the executable shown below. To retrieve the 3rd party token, the library will call the executable using the command specified. The executable’s output must adhere to the response format specified below. It must output the response to stdout. A sample successful executable OIDC response: .. code:: json { "version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:id_token", "id_token": "HEADER.PAYLOAD.SIGNATURE", "expiration_time": 1620499962 } A sample successful executable SAML response: .. code:: json { "version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:saml2", "saml_response": "...", "expiration_time": 1620499962 } A sample executable error response: .. code:: json { "version": 1, "success": false, "code": "401", "message": "Caller not authorized." } These are all required fields for an error response. The code and message fields will be used by the library as part of the thrown exception. Response format fields summary: - ``version``: The version of the JSON output. Currently only version 1 is supported. - ``success``: The status of the response. - When true, the response must contain the 3rd party token, token type, and expiration. The executable must also exit with exit code 0. - When false, the response must contain the error code and message fields and exit with a non-zero value. - ``token_type``: The 3rd party subject token type. Must be - urn:ietf:params:oauth:token-type:jwt - urn:ietf:params:oauth:token-type:id_token - urn:ietf:params:oauth:token-type:saml2 - ``id_token``: The 3rd party OIDC token. - ``saml_response``: The 3rd party SAML response. - ``expiration_time``: The 3rd party subject token expiration time in seconds (unix epoch time). - ``code``: The error code string. - ``message``: The error message. All response types must include both the ``version`` and ``success`` fields. Successful responses must include the ``token_type``, and one of ``id_token`` or ``saml_response``. ``expiration_time`` is optional. If the output file does not contain the ``expiration_time`` field, the response will be considered expired and the executable will be called. 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. ``GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL``: The service account 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. These environment variables can be used by the executable to avoid hard-coding these values. Security considerations The following security practices are highly recommended: Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. Given the complexity of using executable-sourced credentials, it is recommended to use the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party credentials unless 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. If an error occurs during token retrieval, the supplier should return a :class:`google.auth.exceptions.RefreshError` and indicate via the error whether the subject token retrieval is retryable. Any call to the supplier from the Identity Pool credential will send a :class:`google.auth.external_account.SupplierContext` object, which contains the requested audience and subject type. Additionally, the credential will send the :class:`google.auth.transport.requests.Request` passed in the credential refresh call which can be used to make HTTP requests.:: from google.auth import exceptions 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 try: # Attempt to return the valid subject token of the requested type for the requested audience. except Exception as e: # If token retrieval fails, raise a refresh error, setting retryable to true if the client should # attempt to retrieve the subject token again. raise exceptions.RefreshError(e, retryable=True) 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/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`` Where the following variables need to be substituted: * ``$PROJECT_NUMBER``: The project number. * ``$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. If an error occurs during credential retrieval, the supplier should return a :class:`google.auth.exceptions.RefreshError` and indicate via the error whether the credential retrieval is retryable. Any call to the supplier from the Identity Pool credential will send a :class:`google.auth.external_account.SupplierContext` object, which contains the requested audience and subject type. Additionally, the credential will send the :class:`google.auth.transport.requests.Request` passed in the credential refresh call which can be used to make HTTP requests.:: from google.auth import aws from google.auth import exceptions class CustomAwsSecurityCredentialsSupplier(aws.AwsSecurityCredentialsSupplier): def get_aws_security_credentials(self, context, request): audience = context.audience try: # 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) except Exception as e: # If credentials retrieval fails, raise a refresh error, setting retryable to true if the client should # attempt to retrieve the subject token again. raise exceptions.RefreshError(e, retryable=True) 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_credentials_supplier=supplier, # Set supplier. scopes=SCOPES # Set desired scopes. ) Where the `audience`_ is: ``///iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`` Where the following variables need to be substituted: * ``$PROJECT_NUMBER``: The project number. * ``$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 ~~~~~~~~~~~~~~~~~~~~~~~~~ External identities (AWS, Azure and OIDC identity providers) can be used with Application Default Credentials. In order to use external identities with Application Default Credentials, you need to generate the JSON credentials configuration file for your external identity. Once generated, store the path to this file in the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable. .. code-block:: bash $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json The library can now automatically choose the right type of client and initialize credentials from the context provided in the configuration file:: import google.auth credentials, project = google.auth.default() When using external identities with Application Default Credentials, the ``roles/browser`` role needs to be granted to the service account. The ``Cloud Resource Manager API`` should also be enabled on the project. This is needed since :func:`default` will try to auto-discover the project ID from the current environment using the impersonated credential. Otherwise, the project ID will resolve to ``None``. You can override the project detection by setting the ``GOOGLE_CLOUD_PROJECT`` environment variable. You can also explicitly initialize external account clients using the generated configuration file. For Azure and OIDC providers, use :meth:`identity_pool.Credentials.from_info <google.auth.identity_pool.Credentials.from_info>` or :meth:`identity_pool.Credentials.from_file <google.auth.identity_pool.Credentials.from_file>`:: import json from google.auth import identity_pool json_config_info = json.loads(function_to_get_json_config()) credentials = identity_pool.Credentials.from_info(json_config_info) scoped_credentials = credentials.with_scopes( ['https://www.googleapis.com/auth/cloud-platform']) For AWS providers, use :meth:`aws.Credentials.from_info <google.auth.aws.Credentials.from_info>` or :meth:`aws.Credentials.from_file <google.auth.aws.Credentials.from_file>`:: import json from google.auth import aws json_config_info = json.loads(function_to_get_json_config()) credentials = aws.Credentials.from_info(json_config_info) scoped_credentials = credentials.with_scopes( ['https://www.googleapis.com/auth/cloud-platform']) Security considerations ~~~~~~~~~~~~~~~~~~~~~~~ Note that this library does not perform any validation on the token_url, token_info_url, or service_account_impersonation_url fields of the credential configuration. It is not recommended to use a credential configuration that you did not generate with the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain. External credentials (Workforce identity federation) ++++++++++++++++++++++++++++++++++++++++++++++++++++ `Workforce identity federation`_ lets you use an external identify provider (IdP) to authenticate and authorize a workforce—a group of users, such as employees, partners, and contractors—using IAM, so that the users can access Google Cloud services. Workforce identity federation extends Google Cloud's identity capabilities to support syncless, attribute-based single sign on. With workforce identity federation, your workforce can access Google Cloud resources using an external identity provider (IdP) that supports OpenID Connect (OIDC) or SAML 2.0 such as Azure Active Directory (Azure AD), Active Directory Federation Services (AD FS), Okta, and others. Accessing resources using an OIDC or SAML 2.0 identity provider ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to access Google Cloud resources from an identity provider that supports `OpenID Connect (OIDC)`_, the following requirements are needed: - A workforce identity pool needs to be created. - An OIDC or SAML 2.0 identity provider needs to be added in the workforce pool. Follow the detailed `instructions`_ on how to configure workforce identity federation. After configuring an OIDC or SAML 2.0 provider, a credential configuration file needs to be generated. The generated credential configuration file contains non-sensitive metadata to instruct the library on how to retrieve external subject tokens and exchange them for GCP access tokens. The configuration file can be generated by using the `gcloud CLI`_. The Auth library can retrieve external subject tokens from a local file location (file-sourced credentials), from a local server (URL-sourced credentials) or by calling an executable (executable-sourced credentials). File-sourced credentials ++++++++++++++++++++++++ For file-sourced credentials, a background process needs to be continuously refreshing the file location with a new subject token prior to expiration. For tokens with one hour lifetimes, the token needs to be updated in the file every hour. The token can be stored directly as plain text or in JSON format. To generate a file-sourced OIDC configuration, run the following command: .. code-block:: bash # Generate an OIDC configuration file for file-sourced credentials. gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \ --subject-token-type=urn:ietf:params:oauth:token-type:id_token \ --credential-source-file=$PATH_TO_OIDC_ID_TOKEN \ --workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \ # Optional arguments for file types. Default is "text": # --credential-source-type "json" \ # Optional argument for the field that contains the OIDC credential. # This is required for json. # --credential-source-field-name "id_token" \ --output-file=/path/to/generated/config.json Where the following variables need to be substituted: * ``$WORKFORCE_POOL_ID``: The workforce pool ID. * ``$PROVIDER_ID``: The provider ID. * ``$PATH_TO_OIDC_ID_TOKEN``: The file path used to retrieve the OIDC token. * ``$WORKFORCE_POOL_USER_PROJECT``: The project number associated with the `workforce pools user project`_. To generate a file-sourced SAML configuration, run the following command: .. code-block:: bash # Generate a SAML configuration file for file-sourced credentials. gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \ --credential-source-file=$PATH_TO_SAML_ASSERTION \ --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \ --workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \ --output-file=/path/to/generated/config.json Where the following variables need to be substituted: * ``$WORKFORCE_POOL_ID``: The workforce pool ID. * ``$PROVIDER_ID``: The provider ID. * ``$PATH_TO_SAML_ASSERTION``: The file path used to retrieve the base64-encoded SAML assertion. * ``$WORKFORCE_POOL_USER_PROJECT``: The project number associated with the `workforce pools user project`_. These commands generate the configuration file in the specified output file. URL-sourced credentials +++++++++++++++++++++++ For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC token. The response can be in plain text or JSON. Additional required request headers can also be specified. To generate a URL-sourced OIDC workforce identity configuration, run the following command: .. code-block:: bash # Generate an OIDC configuration file for URL-sourced credentials. gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \ --subject-token-type=urn:ietf:params:oauth:token-type:id_token \ --credential-source-url=$URL_TO_RETURN_OIDC_ID_TOKEN \ --credential-source-headers $HEADER_KEY=$HEADER_VALUE \ --workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \ --output-file=/path/to/generated/config.json Where the following variables need to be substituted: * ``$WORKFORCE_POOL_ID``: The workforce pool ID. * ``$PROVIDER_ID``: The provider ID. * ``$URL_TO_RETURN_OIDC_ID_TOKEN``: The URL of the local server endpoint. * ``$HEADER_KEY`` and ``$HEADER_VALUE``: The additional header key/value pairs to pass along the GET request to ``$URL_TO_GET_OIDC_TOKEN``, e.g. ``Metadata-Flavor=Google``. * ``$WORKFORCE_POOL_USER_PROJECT``: The project number associated with the `workforce pools user project`_. To generate a URL-sourced SAML configuration, run the following command: .. code-block:: bash # Generate a SAML configuration file for file-sourced credentials. gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \ --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \ --credential-source-url=$URL_TO_GET_SAML_ASSERTION \ --credential-source-headers $HEADER_KEY=$HEADER_VALUE \ --workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \ --output-file=/path/to/generated/config.json These commands generate the configuration file in the specified output file. Where the following variables need to be substituted: * ``$WORKFORCE_POOL_ID``: The workforce pool ID. * ``$PROVIDER_ID``: The provider ID. * ``$URL_TO_GET_SAML_ASSERTION``: The URL of the local server endpoint. * ``$HEADER_KEY`` and ``$HEADER_VALUE``: The additional header key/value pairs to pass along the GET request to ``$URL_TO_GET_SAML_ASSERTION``, e.g. ``Metadata-Flavor=Google``. * ``$WORKFORCE_POOL_USER_PROJECT``: The project number associated with the `workforce pools user project`_. Using Executable-sourced workforce credentials with OIDC and SAML ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Executable-sourced credentials For executable-sourced credentials, a local executable is used to retrieve the 3rd party token. The executable must handle providing a valid, unexpired OIDC ID token or SAML assertion in JSON format to stdout. To use executable-sourced credentials, the ``GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES`` environment variable must be set to ``1``. To generate an executable-sourced workforce identity configuration, run the following command: .. code-block:: bash # Generate a configuration file for executable-sourced credentials. gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/$WORKFORCE_POOL_ID/providers/$PROVIDER_ID \ --subject-token-type=$SUBJECT_TOKEN_TYPE \ # The absolute path for the program, including arguments. # e.g. --executable-command="/path/to/command --foo=bar" --executable-command=$EXECUTABLE_COMMAND \ # Optional argument for the executable timeout. Defaults to 30s. # --executable-timeout-millis=$EXECUTABLE_TIMEOUT \ # Optional argument for the absolute path to the executable output file. # See below on how this argument impacts the library behaviour. # --executable-output-file=$EXECUTABLE_OUTPUT_FILE \ --workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \ --output-file /path/to/generated/config.json Where the following variables need to be substituted: * ``$WORKFORCE_POOL_ID``: The workforce pool ID. * ``$PROVIDER_ID``: The provider ID. * ``$SUBJECT_TOKEN_TYPE``: The subject token type. * ``$EXECUTABLE_COMMAND``: The full command to run, including arguments. Must be an absolute path to the program. * ``$WORKFORCE_POOL_USER_PROJECT``: The project number associated with the workforce pools user project. The ``--executable-timeout-millis`` flag is optional. This is the duration for which the auth library will wait for the executable to finish, in milliseconds. Defaults to 30 seconds when not provided. The maximum allowed value is 2 minutes. The minimum is 5 seconds. The ``--executable-output-file`` flag is optional. If provided, the file path must point to the 3rd party credential response generated by the executable. This is useful for caching the credentials. By specifying this path, the Auth libraries will first check for its existence before running the executable. By caching the executable JSON response to this file, it improves performance as it avoids the need to run the executable until the cached credentials in the output file are expired. The executable must handle writing to this file - the auth libraries will only attempt to read from this location. The format of contents in the file should match the JSON format expected by the executable shown below. To retrieve the 3rd party token, the library will call the executable using the command specified. The executable's output must adhere to the response format specified below. It must output the response to stdout. 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. If an error occurs during token retrieval, the supplier should return a :class:`google.auth.exceptions.RefreshError` and indicate via the error whether the subject token retrieval is retryable. Any call to the supplier from the Identity Pool credential will send a :class:`google.auth.external_account.SupplierContext` object, which contains the requested audience and subject type. Additionally, the credential will send the :class:`google.auth.transport.requests.Request` passed in the credential refresh call which can be used to make HTTP requests.:: from google.auth import exceptions 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 try: # Attempt to return the valid subject token of the requested type for the requested audience. except Exception as e: # If token retrieval fails, raise a refresh error, setting retryable to true if the client should # attempt to retrieve the subject token again. raise exceptions.RefreshError(e, retryable=True) 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 ~~~~~~~~~~~~~~~~~~~~~~~ The following security practices are highly recommended: * Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. * The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. Given the complexity of using executable-sourced credentials, it is recommended to use the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party credentials unless 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. .. _Workforce Identity Federation: https://cloud.google.com/iam/docs/workforce-identity-federation .. _OpenID Connect (OIDC): https://openid.net/connect/ .. _instructions: https://cloud.google.com/iam/docs/configuring-workforce-identity-federation .. _gcloud CLI: https://cloud.google.com/sdk/ .. _workforce pools user project: https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project Note that this library does not perform any validation on the token_url, token_info_url, or service_account_impersonation_url fields of the credential configuration. It is not recommended to use a credential configuration that you did not generate with the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain. Impersonated credentials ++++++++++++++++++++++++ Impersonated Credentials allows one set of credentials issued to a user or service account to impersonate a service account. Impersonation is the preferred way of using service account for local development over downloading the service account key. The source credentials must be granted the "Service Account Token Creator" IAM role. :: from google.auth import impersonated_credentials target_scopes = ['https://www.googleapis.com/auth/devstorage.read_only'] source_credentials = service_account.Credentials.from_service_account_file( '/path/to/svc_account.json', scopes=target_scopes) target_credentials = impersonated_credentials.Credentials( source_credentials=source_credentials, target_principal='impersonated-account@_project_.iam.gserviceaccount.com', target_scopes=target_scopes, lifetime=500) client = storage.Client(credentials=target_credentials) buckets = client.list_buckets(project='your_project') for bucket in buckets: print(bucket.name) In the example above `source_credentials` does not have direct access to list buckets in the target project. Using `ImpersonatedCredentials` will allow the source_credentials to assume the identity of a target_principal that does have access. It is possible to provide a delegation chain through `delegates` paramter while initializing the impersonated credential. Refer `create short lived credentials delegated`_ for more details on delegation chain. .. _create short lived credentials delegated: https://cloud.google.com/iam/docs/create-short-lived-credentials-delegated Service account private key files +++++++++++++++++++++++++++++++++ A service account private key file can be used to obtain credentials for a service account. If you are not able to use any of the authentication methods listed above, you can create a private key using `Credentials page of the Google Cloud Console`_. Once you have a private key you can obtain credentials one of three ways: 1. Set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to the full path to your service account private key file .. code-block:: bash $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json Then, use :ref:`application default credentials <application-default>`. :func:`default` checks for the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable before all other checks, so this will always use the credentials you explicitly specify. 2. Use :meth:`service_account.Credentials.from_service_account_file <google.oauth2.service_account.Credentials.from_service_account_file>`:: from google.oauth2 import service_account credentials = service_account.Credentials.from_service_account_file( '/path/to/key.json') scoped_credentials = credentials.with_scopes( ['https://www.googleapis.com/auth/cloud-platform']) 3. Use :meth:`service_account.Credentials.from_service_account_info <google.oauth2.service_account.Credentials.from_service_account_info>`:: import json from google.oauth2 import service_account json_acct_info = json.loads(function_to_get_json_creds()) credentials = service_account.Credentials.from_service_account_info( json_acct_info) scoped_credentials = credentials.with_scopes( ['https://www.googleapis.com/auth/cloud-platform']) .. warning:: Private keys must be kept secret. If you expose your private key it is recommended to revoke it immediately from the Google Cloud Console. .. _Credentials page of the Google Cloud Console: https://console.cloud.google.com/apis/credentials Downscoped credentials ++++++++++++++++++++++ `Downscoping with Credential Access Boundaries`_ is used to restrict the Identity and Access Management (IAM) permissions that a short-lived credential can use. To downscope permissions of a source credential, a `Credential Access Boundary` that specifies which resources the new credential can access, as well as an upper bound on the permissions that are available on each resource, has to be defined. A downscoped credential can then be instantiated using the `source_credential` and the `Credential Access Boundary`. The common pattern of usage is to have a token broker with elevated access generate these downscoped credentials from higher access source credentials and pass the downscoped short-lived access tokens to a token consumer via some secure authenticated channel for limited access to Google Cloud Storage resources. .. _Downscoping with Credential Access Boundaries: https://cloud.google.com/iam/docs/downscoping-short-lived-credentials Token broker :: import google.auth from google.auth import downscoped from google.auth.transport import requests # Initialize the credential access boundary rules. available_resource = '//storage.googleapis.com/projects/_/buckets/bucket-123' available_permissions = ['inRole:roles/storage.objectViewer'] availability_expression = ( "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')" ) availability_condition = downscoped.AvailabilityCondition( availability_expression) rule = downscoped.AccessBoundaryRule( available_resource=available_resource, available_permissions=available_permissions, availability_condition=availability_condition) credential_access_boundary = downscoped.CredentialAccessBoundary( rules=[rule]) # Retrieve the source credentials via ADC. source_credentials, _ = google.auth.default() # Create the downscoped credentials. downscoped_credentials = downscoped.Credentials( source_credentials=source_credentials, credential_access_boundary=credential_access_boundary) # Refresh the tokens. downscoped_credentials.refresh(requests.Request()) # These values will need to be passed to the Token Consumer. access_token = downscoped_credentials.token expiry = downscoped_credentials.expiry For example, a token broker can be set up on a server in a private network. Various workloads (token consumers) in the same network will send authenticated requests to that broker for downscoped tokens to access or modify specific google cloud storage buckets. The broker will instantiate downscoped credentials instances that can be used to generate short lived downscoped access tokens that can be passed to the token consumer. These downscoped access tokens can be injected by the consumer into `google.oauth2.Credentials` and used to initialize a storage client instance to access Google Cloud Storage resources with restricted access. Token Consumer :: import google.oauth2 from google.auth.transport import requests from google.cloud import storage # Downscoped token retrieved from token broker. # The `get_token_from_broker` callable requests a token and an expiry # from the token broker. downscoped_token, expiry = get_token_from_broker( requests.Request(), scopes=['https://www.googleapis.com/auth/cloud-platform']) # Create the OAuth credentials from the downscoped token and pass a # refresh handler to handle token expiration. Passing the original # downscoped token or the expiry here is optional, as the refresh_handler # will generate the downscoped token on demand. credentials = google.oauth2.credentials.Credentials( downscoped_token, expiry=expiry, scopes=['https://www.googleapis.com/auth/cloud-platform'], refresh_handler=get_token_from_broker) # Initialize a storage client with the oauth2 credentials. storage_client = storage.Client( project='my_project_id', credentials=credentials) # Call GCS APIs. # The token broker has readonly access to objects starting with "customer-a" # in bucket "bucket-123". bucket = storage_client.bucket('bucket-123') blob = bucket.blob('customer-a-data.txt') print(blob.download_as_bytes().decode("utf-8")) Another reason to use downscoped credentials is to ensure tokens in flight always have the least privileges, e.g. Principle of Least Privilege. :: # Create the downscoped credentials. downscoped_credentials = downscoped.Credentials( # source_credentials have elevated access but only a subset of # these permissions are needed here. source_credentials=source_credentials, credential_access_boundary=credential_access_boundary) # Pass the token directly. storage_client = storage.Client( project='my_project_id', credentials=downscoped_credentials) # If the source credentials have elevated levels of access, the # token in flight here will have limited readonly access to objects # starting with "customer-a" in bucket "bucket-123". bucket = storage_client.bucket('bucket-123') blob = bucket.blob('customer-a-data.txt') print(blob.download_as_string()) Note: Only Cloud Storage supports Credential Access Boundaries. Other Google Cloud services do not support this feature. Identity Tokens +++++++++++++++ `Google OpenID Connect`_ tokens are available through :mod:`Service Account <google.oauth2.service_account>`, :mod:`Impersonated <google.auth.impersonated_credentials>`, and :mod:`Compute Engine <google.auth.compute_engine>`. These tokens can be used to authenticate against `Cloud Functions`_, `Cloud Run`_, a user service behind `Identity Aware Proxy`_ or any other service capable of verifying a `Google ID Token`_. ServiceAccount :: from google.oauth2 import service_account target_audience = 'https://example.com' creds = service_account.IDTokenCredentials.from_service_account_file( '/path/to/svc.json', target_audience=target_audience) Compute :: from google.auth import compute_engine import google.auth.transport.requests target_audience = 'https://example.com' request = google.auth.transport.requests.Request() creds = compute_engine.IDTokenCredentials(request, target_audience=target_audience) Impersonated :: from google.auth import impersonated_credentials # get target_credentials from a source_credential target_audience = 'https://example.com' creds = impersonated_credentials.IDTokenCredentials( target_credentials, target_audience=target_audience) If your application runs on `App Engine`_, `Cloud Run`_, `Compute Engine`_, or has application default credentials set via `GOOGLE_APPLICATION_CREDENTIALS` environment variable, you can also use `google.oauth2.id_token.fetch_id_token` to obtain an ID token from your current running environment. The following is an example :: import google.oauth2.id_token import google.auth.transport.requests request = google.auth.transport.requests.Request() target_audience = "https://pubsub.googleapis.com" id_token = google.oauth2.id_token.fetch_id_token(request, target_audience) IDToken verification can be done for various type of IDTokens using the :class:`google.oauth2.id_token` module. It supports ID token signed with RS256 and ES256 algorithms. However, ES256 algorithm won't be available unless `cryptography` dependency of version at least 1.4.0 is installed. You can check the dependency with `pip freeze` or try `from google.auth.crypt import es256`. The following is an example of verifying ID tokens :: from google.auth2 import id_token request = google.auth.transport.requests.Request() try: decoded_token = id_token.verify_token(token_to_verify,request) except ValueError: # Verification failed. A sample end-to-end flow using an ID Token against a Cloud Run endpoint maybe :: from google.oauth2 import id_token from google.oauth2 import service_account import google.auth import google.auth.transport.requests from google.auth.transport.requests import AuthorizedSession target_audience = 'https://your-cloud-run-app.a.run.app' url = 'https://your-cloud-run-app.a.run.app' creds = service_account.IDTokenCredentials.from_service_account_file( '/path/to/svc.json', target_audience=target_audience) authed_session = AuthorizedSession(creds) # make authenticated request and print the response, status_code resp = authed_session.get(url) print(resp.status_code) print(resp.text) # to verify an ID Token request = google.auth.transport.requests.Request() token = creds.token print(token) print(id_token.verify_token(token,request)) .. _App Engine: https://cloud.google.com/appengine/ .. _Cloud Functions: https://cloud.google.com/functions/ .. _Cloud Run: https://cloud.google.com/run/ .. _Identity Aware Proxy: https://cloud.google.com/iap/ .. _Google OpenID Connect: https://developers.google.com/identity/protocols/OpenIDConnect .. _Google ID Token: https://developers.google.com/identity/protocols/OpenIDConnect#validatinganidtoken Making authenticated requests ----------------------------- Once you have credentials you can attach them to a transport. You can then use this transport to make authenticated requests to APIs. google-auth supports several different transports. Typically, it's up to your application or an opinionated client library to decide which transport to use. Requests ++++++++ The recommended HTTP transport is :mod:`google.auth.transport.requests` which uses the `Requests`_ library. To make authenticated requests using Requests you use a custom `Session`_ object:: from google.auth.transport.requests import AuthorizedSession authed_session = AuthorizedSession(credentials) response = authed_session.get( 'https://www.googleapis.com/storage/v1/b') .. _Requests: http://docs.python-requests.org/en/master/ .. _Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects urllib3 +++++++ :mod:`urllib3` is the underlying HTTP library used by Requests and can also be used with google-auth. urllib3's interface isn't as high-level as Requests but it can be useful in situations where you need more control over how HTTP requests are made. To make authenticated requests using urllib3 create an instance of :class:`google.auth.transport.urllib3.AuthorizedHttp`:: from google.auth.transport.urllib3 import AuthorizedHttp authed_http = AuthorizedHttp(credentials) response = authed_http.request( 'GET', 'https://www.googleapis.com/storage/v1/b') You can also construct your own :class:`urllib3.PoolManager` instance and pass it to :class:`~google.auth.transport.urllib3.AuthorizedHttp`:: import urllib3 http = urllib3.PoolManager() authed_http = AuthorizedHttp(credentials, http) gRPC ++++ `gRPC`_ is an RPC framework that uses `Protocol Buffers`_ over `HTTP 2.0`_. google-auth can provide `Call Credentials`_ for gRPC. The easiest way to do this is to use google-auth to create the gRPC channel:: import google.auth.transport.grpc import google.auth.transport.requests http_request = google.auth.transport.requests.Request() channel = google.auth.transport.grpc.secure_authorized_channel( credentials, http_request, 'pubsub.googleapis.com:443') .. note:: Even though gRPC is its own transport, you still need to use one of the other HTTP transports with gRPC. The reason is that most credential types need to make HTTP requests in order to refresh their access token. The sample above uses the Requests transport, but any HTTP transport can be used. Additionally, if you know that your credentials do not need to make HTTP requests in order to refresh (as is the case with :class:`jwt.Credentials`) then you can specify ``None``. Alternatively, you can create the channel yourself and use :class:`google.auth.transport.grpc.AuthMetadataPlugin`:: import grpc metadata_plugin = AuthMetadataPlugin(credentials, http_request) # Create a set of grpc.CallCredentials using the metadata plugin. google_auth_credentials = grpc.metadata_call_credentials( metadata_plugin) # Create SSL channel credentials. ssl_credentials = grpc.ssl_channel_credentials() # Combine the ssl credentials and the authorization credentials. composite_credentials = grpc.composite_channel_credentials( ssl_credentials, google_auth_credentials) channel = grpc.secure_channel( 'pubsub.googleapis.com:443', composite_credentials) You can use this channel to make a gRPC stub that makes authenticated requests to a gRPC service:: from google.pubsub.v1 import pubsub_pb2 pubsub = pubsub_pb2.PublisherStub(channel) response = pubsub.ListTopics( pubsub_pb2.ListTopicsRequest(project='your-project')) .. _gRPC: http://www.grpc.io/ .. _Protocol Buffers: https://developers.google.com/protocol-buffers/docs/overview .. _HTTP 2.0: http://www.grpc.io/docs/guides/wire.html .. _Call Credentials: http://www.grpc.io/docs/guides/auth.html	58.49 KB	2025-04-14 17:36

Terminal