google-auth 2.46.0__py3-none-any.whl

google/auth/__init__.py

@@ -0,0 +1,53 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Google Auth Library for Python."""
+
+import logging
+import sys
+import warnings
+
+from google.auth import version as google_auth_version
+from google.auth._default import (
+    default,
+    load_credentials_from_dict,
+    load_credentials_from_file,
+)
+
+
+__version__ = google_auth_version.__version__
+
+
+__all__ = ["default", "load_credentials_from_file", "load_credentials_from_dict"]
+
+
+class Python37DeprecationWarning(DeprecationWarning):  # pragma: NO COVER
+    """
+    Deprecation warning raised when Python 3.7 runtime is detected.
+    Python 3.7 support will be dropped after January 1, 2024.
+    """
+
+    pass
+
+
+# Checks if the current runtime is Python 3.7.
+if sys.version_info.major == 3 and sys.version_info.minor == 7:  # pragma: NO COVER
+    message = (
+        "After January 1, 2024, new releases of this library will drop support "
+        "for Python 3.7."
+    )
+    warnings.warn(message, Python37DeprecationWarning)
+
+# Set default logging handler to avoid "No handler found" warnings.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

google/auth/_agent_identity_utils.py

@@ -0,0 +1,281 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helpers for Agent Identity credentials."""
+
+import base64
+import hashlib
+import logging
+import os
+import re
+import time
+from urllib.parse import quote, urlparse
+
+from google.auth import environment_vars
+from google.auth import exceptions
+from google.auth.transport import _mtls_helper
+
+
+_LOGGER = logging.getLogger(__name__)
+
+CRYPTOGRAPHY_NOT_FOUND_ERROR = (
+    "The cryptography library is required for certificate-based authentication."
+    "Please install it with `pip install google-auth[cryptography]`."
+)
+
+# SPIFFE trust domain patterns for Agent Identities.
+_AGENT_IDENTITY_SPIFFE_TRUST_DOMAIN_PATTERNS = [
+    r"^agents\.global\.org-\d+\.system\.id\.goog$",
+    r"^agents\.global\.proj-\d+\.system\.id\.goog$",
+]
+
+_WELL_KNOWN_CERT_PATH = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
+
+# Constants for polling the certificate file.
+_FAST_POLL_CYCLES = 50
+_FAST_POLL_INTERVAL = 0.1  # 100ms
+_SLOW_POLL_INTERVAL = 0.5  # 500ms
+_TOTAL_TIMEOUT = 30  # seconds
+
+# Calculate the number of slow poll cycles based on the total timeout.
+_SLOW_POLL_CYCLES = int(
+    (_TOTAL_TIMEOUT - (_FAST_POLL_CYCLES * _FAST_POLL_INTERVAL)) / _SLOW_POLL_INTERVAL
+)
+
+_POLLING_INTERVALS = ([_FAST_POLL_INTERVAL] * _FAST_POLL_CYCLES) + (
+    [_SLOW_POLL_INTERVAL] * _SLOW_POLL_CYCLES
+)
+
+
+def _is_certificate_file_ready(path):
+    """Checks if a file exists and is not empty."""
+    return path and os.path.exists(path) and os.path.getsize(path) > 0
+
+
+def get_agent_identity_certificate_path():
+    """Gets the certificate path from the certificate config file.
+
+    The path to the certificate config file is read from the
+    GOOGLE_API_CERTIFICATE_CONFIG environment variable. This function
+    implements a retry mechanism to handle cases where the environment
+    variable is set before the files are available on the filesystem.
+
+    Returns:
+        str: The path to the leaf certificate file.
+
+    Raises:
+        google.auth.exceptions.RefreshError: If the certificate config file
+            or the certificate file cannot be found after retries.
+    """
+    import json
+
+    cert_config_path = os.environ.get(environment_vars.GOOGLE_API_CERTIFICATE_CONFIG)
+    if not cert_config_path:
+        return None
+
+    has_logged_warning = False
+
+    for interval in _POLLING_INTERVALS:
+        try:
+            with open(cert_config_path, "r") as f:
+                cert_config = json.load(f)
+                cert_path = (
+                    cert_config.get("cert_configs", {})
+                    .get("workload", {})
+                    .get("cert_path")
+                )
+                if _is_certificate_file_ready(cert_path):
+                    return cert_path
+        except (IOError, ValueError, KeyError):
+            if not has_logged_warning:
+                _LOGGER.warning(
+                    "Certificate config file not found at %s (from %s environment "
+                    "variable). Retrying for up to %s seconds.",
+                    cert_config_path,
+                    environment_vars.GOOGLE_API_CERTIFICATE_CONFIG,
+                    _TOTAL_TIMEOUT,
+                )
+                has_logged_warning = True
+            pass
+
+        # As a fallback, check the well-known certificate path.
+        if _is_certificate_file_ready(_WELL_KNOWN_CERT_PATH):
+            return _WELL_KNOWN_CERT_PATH
+
+        # A sleep is required in two cases:
+        # 1. The config file is not found (the except block).
+        # 2. The config file is found, but the certificate is not yet available.
+        # In both cases, we need to poll, so we sleep on every iteration
+        # that doesn't return a certificate.
+        time.sleep(interval)
+
+    raise exceptions.RefreshError(
+        "Certificate config or certificate file not found after multiple retries. "
+        f"Token binding protection is failing. You can turn off this protection by setting "
+        f"{environment_vars.GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES} to false "
+        "to fall back to unbound tokens."
+    )
+
+
+def get_and_parse_agent_identity_certificate():
+    """Gets and parses the agent identity certificate if not opted out.
+
+    Checks if the user has opted out of certificate-bound tokens. If not,
+    it gets the certificate path, reads the file, and parses it.
+
+    Returns:
+        The parsed certificate object if found and not opted out, otherwise None.
+    """
+    # If the user has opted out of cert bound tokens, there is no need to
+    # look up the certificate.
+    is_opted_out = (
+        os.environ.get(
+            environment_vars.GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES,
+            "true",
+        ).lower()
+        == "false"
+    )
+    if is_opted_out:
+        return None
+
+    cert_path = get_agent_identity_certificate_path()
+    if not cert_path:
+        return None
+
+    with open(cert_path, "rb") as cert_file:
+        cert_bytes = cert_file.read()
+
+    return parse_certificate(cert_bytes)
+
+
+def parse_certificate(cert_bytes):
+    """Parses a PEM-encoded certificate.
+
+    Args:
+        cert_bytes (bytes): The PEM-encoded certificate bytes.
+
+    Returns:
+        cryptography.x509.Certificate: The parsed certificate object.
+    """
+    try:
+        from cryptography import x509
+
+        return x509.load_pem_x509_certificate(cert_bytes)
+    except ImportError as e:
+        raise ImportError(CRYPTOGRAPHY_NOT_FOUND_ERROR) from e
+
+
+def _is_agent_identity_certificate(cert):
+    """Checks if a certificate is an Agent Identity certificate.
+
+    This is determined by checking the Subject Alternative Name (SAN) for a
+    SPIFFE ID with a trust domain matching Agent Identity patterns.
+
+    Args:
+        cert (cryptography.x509.Certificate): The parsed certificate object.
+
+    Returns:
+        bool: True if the certificate is an Agent Identity certificate,
+            False otherwise.
+    """
+    try:
+        from cryptography import x509
+        from cryptography.x509.oid import ExtensionOID
+
+        try:
+            ext = cert.extensions.get_extension_for_oid(
+                ExtensionOID.SUBJECT_ALTERNATIVE_NAME
+            )
+        except x509.ExtensionNotFound:
+            return False
+        uris = ext.value.get_values_for_type(x509.UniformResourceIdentifier)
+
+        for uri in uris:
+            parsed_uri = urlparse(uri)
+            if parsed_uri.scheme == "spiffe":
+                trust_domain = parsed_uri.netloc
+                for pattern in _AGENT_IDENTITY_SPIFFE_TRUST_DOMAIN_PATTERNS:
+                    if re.match(pattern, trust_domain):
+                        return True
+        return False
+    except ImportError as e:
+        raise ImportError(CRYPTOGRAPHY_NOT_FOUND_ERROR) from e
+
+
+def calculate_certificate_fingerprint(cert):
+    """Calculates the URL-encoded, unpadded, base64-encoded SHA256 hash of a
+    DER-encoded certificate.
+
+    Args:
+        cert (cryptography.x509.Certificate): The parsed certificate object.
+
+    Returns:
+        str: The URL-encoded, unpadded, base64-encoded SHA256 fingerprint.
+    """
+    try:
+        from cryptography.hazmat.primitives import serialization
+
+        der_cert = cert.public_bytes(serialization.Encoding.DER)
+        fingerprint = hashlib.sha256(der_cert).digest()
+        # The certificate fingerprint is generated in two steps to align with GFE's
+        # expectations and ensure proper URL transmission:
+        # 1. Standard base64 encoding is applied, and padding ('=') is removed.
+        # 2. The resulting string is then URL-encoded to handle special characters
+        #    ('+', '/') that would otherwise be misinterpreted in URL parameters.
+        base64_fingerprint = base64.b64encode(fingerprint).decode("utf-8")
+        unpadded_base64_fingerprint = base64_fingerprint.rstrip("=")
+        return quote(unpadded_base64_fingerprint)
+    except ImportError as e:
+        raise ImportError(CRYPTOGRAPHY_NOT_FOUND_ERROR) from e
+
+
+def should_request_bound_token(cert):
+    """Determines if a bound token should be requested.
+
+    This is based on the GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES
+    environment variable and whether the certificate is an agent identity cert.
+
+    Args:
+        cert (cryptography.x509.Certificate): The parsed certificate object.
+
+    Returns:
+        bool: True if a bound token should be requested, False otherwise.
+    """
+    is_agent_cert = _is_agent_identity_certificate(cert)
+    is_opted_in = (
+        os.environ.get(
+            environment_vars.GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES,
+            "true",
+        ).lower()
+        == "true"
+    )
+    return is_agent_cert and is_opted_in
+
+
+def call_client_cert_callback():
+    """Calls the client cert callback and returns the certificate and key."""
+    _, cert_bytes, key_bytes, passphrase = _mtls_helper.get_client_ssl_credentials(
+        generate_encrypted_key=True
+    )
+    return cert_bytes, key_bytes
+
+
+def get_cached_cert_fingerprint(cached_cert):
+    """Returns the fingerprint of the cached certificate."""
+    if cached_cert:
+        cert_obj = parse_certificate(cached_cert)
+        cached_cert_fingerprint = calculate_certificate_fingerprint(cert_obj)
+    else:
+        raise ValueError("mTLS connection is not configured.")
+    return cached_cert_fingerprint

google/auth/_cloud_sdk.py

@@ -0,0 +1,153 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Helpers for reading the Google Cloud SDK's configuration."""
+
+import os
+import subprocess
+
+from google.auth import _helpers
+from google.auth import environment_vars
+from google.auth import exceptions
+
+
+# The ~/.config subdirectory containing gcloud credentials.
+_CONFIG_DIRECTORY = "gcloud"
+# Windows systems store config at %APPDATA%\gcloud
+_WINDOWS_CONFIG_ROOT_ENV_VAR = "APPDATA"
+# The name of the file in the Cloud SDK config that contains default
+# credentials.
+_CREDENTIALS_FILENAME = "application_default_credentials.json"
+# The name of the Cloud SDK shell script
+_CLOUD_SDK_POSIX_COMMAND = "gcloud"
+_CLOUD_SDK_WINDOWS_COMMAND = "gcloud.cmd"
+# The command to get the Cloud SDK configuration
+_CLOUD_SDK_CONFIG_GET_PROJECT_COMMAND = ("config", "get", "project")
+# The command to get google user access token
+_CLOUD_SDK_USER_ACCESS_TOKEN_COMMAND = ("auth", "print-access-token")
+# Cloud SDK's application-default client ID
+CLOUD_SDK_CLIENT_ID = (
+    "764086051850-6qr4p6gpi6hn506pt8ejuq83di341hur.apps.googleusercontent.com"
+)
+
+
+def get_config_path():
+    """Returns the absolute path the the Cloud SDK's configuration directory.
+
+    Returns:
+        str: The Cloud SDK config path.
+    """
+    # If the path is explicitly set, return that.
+    try:
+        return os.environ[environment_vars.CLOUD_SDK_CONFIG_DIR]
+    except KeyError:
+        pass
+
+    # Non-windows systems store this at ~/.config/gcloud
+    if os.name != "nt":
+        return os.path.join(os.path.expanduser("~"), ".config", _CONFIG_DIRECTORY)
+    # Windows systems store config at %APPDATA%\gcloud
+    else:
+        try:
+            return os.path.join(
+                os.environ[_WINDOWS_CONFIG_ROOT_ENV_VAR], _CONFIG_DIRECTORY
+            )
+        except KeyError:
+            # This should never happen unless someone is really
+            # messing with things, but we'll cover the case anyway.
+            drive = os.environ.get("SystemDrive", "C:")
+            return os.path.join(drive, "\\", _CONFIG_DIRECTORY)
+
+
+def get_application_default_credentials_path():
+    """Gets the path to the application default credentials file.
+
+    The path may or may not exist.
+
+    Returns:
+        str: The full path to application default credentials.
+    """
+    config_path = get_config_path()
+    return os.path.join(config_path, _CREDENTIALS_FILENAME)
+
+
+def _run_subprocess_ignore_stderr(command):
+    """Return subprocess.check_output with the given command and ignores stderr."""
+    with open(os.devnull, "w") as devnull:
+        output = subprocess.check_output(command, stderr=devnull)
+    return output
+
+
+def get_project_id():
+    """Gets the project ID from the Cloud SDK.
+
+    Returns:
+        Optional[str]: The project ID.
+    """
+    if os.name == "nt":
+        command = _CLOUD_SDK_WINDOWS_COMMAND
+    else:
+        command = _CLOUD_SDK_POSIX_COMMAND
+
+    try:
+        # Ignore the stderr coming from gcloud, so it won't be mixed into the output.
+        # https://github.com/googleapis/google-auth-library-python/issues/673
+        project = _run_subprocess_ignore_stderr(
+            (command,) + _CLOUD_SDK_CONFIG_GET_PROJECT_COMMAND
+        )
+
+        # Turn bytes into a string and remove "\n"
+        project = _helpers.from_bytes(project).strip()
+        return project if project else None
+    except (subprocess.CalledProcessError, OSError, IOError):
+        return None
+
+
+def get_auth_access_token(account=None):
+    """Load user access token with the ``gcloud auth print-access-token`` command.
+
+    Args:
+        account (Optional[str]): Account to get the access token for. If not
+            specified, the current active account will be used.
+
+    Returns:
+        str: The user access token.
+
+    Raises:
+        google.auth.exceptions.UserAccessTokenError: if failed to get access
+            token from gcloud.
+    """
+    if os.name == "nt":
+        command = _CLOUD_SDK_WINDOWS_COMMAND
+    else:
+        command = _CLOUD_SDK_POSIX_COMMAND
+
+    try:
+        if account:
+            command = (
+                (command,)
+                + _CLOUD_SDK_USER_ACCESS_TOKEN_COMMAND
+                + ("--account=" + account,)
+            )
+        else:
+            command = (command,) + _CLOUD_SDK_USER_ACCESS_TOKEN_COMMAND
+
+        access_token = subprocess.check_output(command, stderr=subprocess.STDOUT)
+        # remove the trailing "\n"
+        return access_token.decode("utf-8").strip()
+    except (subprocess.CalledProcessError, OSError, IOError) as caught_exc:
+        new_exc = exceptions.UserAccessTokenError(
+            "Failed to obtain access token", caught_exc
+        )
+        raise new_exc from caught_exc

google/auth/_constants.py

@@ -0,0 +1,5 @@
+"""Shared constants."""
+
+_SERVICE_ACCOUNT_TRUST_BOUNDARY_LOOKUP_ENDPOINT = "https://iamcredentials.{universe_domain}/v1/projects/-/serviceAccounts/{service_account_email}/allowedLocations"
+_WORKFORCE_POOL_TRUST_BOUNDARY_LOOKUP_ENDPOINT = "https://iamcredentials.{universe_domain}/v1/locations/global/workforcePools/{pool_id}/allowedLocations"
+_WORKLOAD_IDENTITY_POOL_TRUST_BOUNDARY_LOOKUP_ENDPOINT = "https://iamcredentials.{universe_domain}/v1/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/allowedLocations"

google/auth/_credentials_async.py

@@ -0,0 +1,171 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Interfaces for credentials."""
+
+import abc
+import inspect
+
+from google.auth import credentials
+
+
+class Credentials(credentials.Credentials, metaclass=abc.ABCMeta):
+    """Async inherited credentials class from google.auth.credentials.
+    The added functionality is the before_request call which requires
+    async/await syntax.
+    All credentials have a :attr:`token` that is used for authentication and
+    may also optionally set an :attr:`expiry` to indicate when the token will
+    no longer be valid.
+
+    Most credentials will be :attr:`invalid` until :meth:`refresh` is called.
+    Credentials can do this automatically before the first HTTP request in
+    :meth:`before_request`.
+
+    Although the token and expiration will change as the credentials are
+    :meth:`refreshed <refresh>` and used, credentials should be considered
+    immutable. Various credentials will accept configuration such as private
+    keys, scopes, and other options. These options are not changeable after
+    construction. Some classes will provide mechanisms to copy the credentials
+    with modifications such as :meth:`ScopedCredentials.with_scopes`.
+    """
+
+    async def before_request(self, request, method, url, headers):
+        """Performs credential-specific before request logic.
+
+        Refreshes the credentials if necessary, then calls :meth:`apply` to
+        apply the token to the authentication header.
+
+        Args:
+            request (google.auth.transport.Request): The object used to make
+                HTTP requests.
+            method (str): The request's HTTP method or the RPC method being
+                invoked.
+            url (str): The request's URI or the RPC service's URI.
+            headers (Mapping): The request's headers.
+        """
+        # pylint: disable=unused-argument
+        # (Subclasses may use these arguments to ascertain information about
+        # the http request.)
+
+        if not self.valid:
+            if inspect.iscoroutinefunction(self.refresh):
+                await self.refresh(request)
+            else:
+                self.refresh(request)
+        self.apply(headers)
+
+
+class CredentialsWithQuotaProject(credentials.CredentialsWithQuotaProject):
+    """Abstract base for credentials supporting ``with_quota_project`` factory"""
+
+
+class AnonymousCredentials(credentials.AnonymousCredentials, Credentials):
+    """Credentials that do not provide any authentication information.
+
+    These are useful in the case of services that support anonymous access or
+    local service emulators that do not use credentials. This class inherits
+    from the sync anonymous credentials file, but is kept if async credentials
+    is initialized and we would like anonymous credentials.
+    """
+
+
+class ReadOnlyScoped(credentials.ReadOnlyScoped, metaclass=abc.ABCMeta):
+    """Interface for credentials whose scopes can be queried.
+
+    OAuth 2.0-based credentials allow limiting access using scopes as described
+    in `RFC6749 Section 3.3`_.
+    If a credential class implements this interface then the credentials either
+    use scopes in their implementation.
+
+    Some credentials require scopes in order to obtain a token. You can check
+    if scoping is necessary with :attr:`requires_scopes`::
+
+        if credentials.requires_scopes:
+            # Scoping is required.
+            credentials = _credentials_async.with_scopes(scopes=['one', 'two'])
+
+    Credentials that require scopes must either be constructed with scopes::
+
+        credentials = SomeScopedCredentials(scopes=['one', 'two'])
+
+    Or must copy an existing instance using :meth:`with_scopes`::
+
+        scoped_credentials = _credentials_async.with_scopes(scopes=['one', 'two'])
+
+    Some credentials have scopes but do not allow or require scopes to be set,
+    these credentials can be used as-is.
+
+    .. _RFC6749 Section 3.3: https://tools.ietf.org/html/rfc6749#section-3.3
+    """
+
+
+class Scoped(credentials.Scoped):
+    """Interface for credentials whose scopes can be replaced while copying.
+
+    OAuth 2.0-based credentials allow limiting access using scopes as described
+    in `RFC6749 Section 3.3`_.
+    If a credential class implements this interface then the credentials either
+    use scopes in their implementation.
+
+    Some credentials require scopes in order to obtain a token. You can check
+    if scoping is necessary with :attr:`requires_scopes`::
+
+        if credentials.requires_scopes:
+            # Scoping is required.
+            credentials = _credentials_async.create_scoped(['one', 'two'])
+
+    Credentials that require scopes must either be constructed with scopes::
+
+        credentials = SomeScopedCredentials(scopes=['one', 'two'])
+
+    Or must copy an existing instance using :meth:`with_scopes`::
+
+        scoped_credentials = credentials.with_scopes(scopes=['one', 'two'])
+
+    Some credentials have scopes but do not allow or require scopes to be set,
+    these credentials can be used as-is.
+
+    .. _RFC6749 Section 3.3: https://tools.ietf.org/html/rfc6749#section-3.3
+    """
+
+
+def with_scopes_if_required(credentials, scopes):
+    """Creates a copy of the credentials with scopes if scoping is required.
+
+    This helper function is useful when you do not know (or care to know) the
+    specific type of credentials you are using (such as when you use
+    :func:`google.auth.default`). This function will call
+    :meth:`Scoped.with_scopes` if the credentials are scoped credentials and if
+    the credentials require scoping. Otherwise, it will return the credentials
+    as-is.
+
+    Args:
+        credentials (google.auth.credentials.Credentials): The credentials to
+            scope if necessary.
+        scopes (Sequence[str]): The list of scopes to use.
+
+    Returns:
+        google.auth._credentials_async.Credentials: Either a new set of scoped
+            credentials, or the passed in credentials instance if no scoping
+            was required.
+    """
+    if isinstance(credentials, Scoped) and credentials.requires_scopes:
+        return credentials.with_scopes(scopes)
+    else:
+        return credentials
+
+
+class Signing(credentials.Signing, metaclass=abc.ABCMeta):
+    """Interface for credentials that can cryptographically sign messages."""