{"id":868,"library":"gcloud-aio-auth","title":"Google Cloud Async I/O Authentication Client","description":"gcloud-aio-auth is an asyncio-compatible Python client library for Google Cloud Authentication. It provides asynchronous primitives for managing access tokens, IAP tokens, and interacting with IAM. Part of the broader `gcloud-aio` monorepo, it offers async interfaces to various Google Cloud services. The current version is 5.4.4, with releases occurring as part of the actively developed monorepo, often tied to dependency updates or new feature rollouts across components.","status":"active","version":"5.4.4","language":"python","source_language":"en","source_url":"https://github.com/talkiq/gcloud-aio","tags":["google cloud","authentication","async","aiohttp","gcp"],"install":[{"cmd":"pip install gcloud-aio-auth","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version.","package":"python","optional":false},{"reason":"Core dependency for asynchronous HTTP requests.","package":"aiohttp","optional":false},{"reason":"Underlying Google authentication mechanisms.","package":"google-auth","optional":false}],"imports":[{"note":"Primary class for managing Google Cloud OAuth 2.0 access tokens.","symbol":"Token","correct":"from gcloud.aio.auth import Token"},{"note":"Class for handling OpenID Connect ID tokens for IAP-secured services.","symbol":"IapToken","correct":"from gcloud.aio.auth import IapToken"},{"note":"Client for interacting with Google Cloud IAM public keys and URL signing.","symbol":"IamClient","correct":"from gcloud.aio.auth import IamClient"}],"quickstart":{"code":"import asyncio\nimport os\nimport aiohttp\nfrom gcloud.aio.auth import Token\n\nasync def main():\n    # Attempt to use GOOGLE_APPLICATION_CREDENTIALS environment variable or ADC\n    # For local development, ensure `gcloud auth application-default login` has been run\n    # or GOOGLE_APPLICATION_CREDENTIALS points to a service account key file.\n    service_account_path = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', '')\n    \n    print(\"Initializing Token...\")\n    # Initialize Token; it will try to discover credentials if service_file is None.\n    # Specify necessary scopes for your application.\n    token = Token(\n        service_file=service_account_path if service_account_path else None,\n        scopes=[\"https://www.googleapis.com/auth/cloud-platform\"]\n    )\n    \n    async with aiohttp.ClientSession() as session:\n        try:\n            # Get an access token (automatically refreshed by the Token instance)\n            access_token = await token.get()\n            print(f\"Successfully obtained access token (first 10 chars): {access_token[:10]}...\")\n            \n            # Example: Make an authenticated request to a Google Cloud API\n            # (e.g., list buckets in Google Cloud Storage)\n            headers = {\"Authorization\": f\"Bearer {access_token}\"}\n            print(\"Making a dummy authenticated request to Google Cloud Storage API...\")\n            async with session.get(\n                \"https://www.googleapis.com/storage/v1/projects/_/buckets\",\n                headers=headers\n            ) as response:\n                if response.status == 200:\n                    print(f\"Request to GCS successful (status 200). Some buckets (if any): {await response.json()}\")\n                else:\n                    print(f\"Request failed with status: {response.status}\")\n                    print(f\"Response body: {await response.text()}\")\n                    \n        except Exception as e:\n            print(f\"An error occurred: {e}\")\n        finally:\n            # Ensure the token's internal session is closed\n            await token.close()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to initialize the `Token` class, which handles credential discovery (via `GOOGLE_APPLICATION_CREDENTIALS` or Application Default Credentials) and automatic token refreshing. It then shows how to use the obtained access token to make an authenticated request using `aiohttp.ClientSession` to a Google Cloud API. Remember to run `gcloud auth application-default login` for local development or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable."},"warnings":[{"fix":"Upgrade Python environment to version 3.10 or later.","message":"Python 3.9 support was dropped in gcloud-aio-auth version 5.4.4. Users on Python 3.9 must upgrade their Python version to 3.10 or newer. [cite: auth-5.4.4 release notes]","severity":"breaking","affected_versions":">=5.4.4"},{"fix":"Upgrade to gcloud-aio-auth>=5.4.4. If manually managing `aiohttp.ClientSession`, ensure `auto_decompress=None` is explicitly set on the `Token` (or other gcloud-aio client) constructor if you want to avoid overwriting your session's setting.","message":"The `auto_decompress` parameter in `aiohttp.ClientSession` could be inadvertently overwritten by `gcloud-aio-auth` in versions prior to 5.4.4. If you explicitly configure `auto_decompress` on your `ClientSession`, ensure you are on version 5.4.4 or later. [cite: auth-5.4.4 release notes, 7]","severity":"gotcha","affected_versions":"<5.4.4"},{"fix":"Always initialize `gcloud.aio.auth.Token` (or `IapToken`) as described in `gcloud-aio-auth` documentation, letting it handle credential discovery or providing a `service_file` directly. Do not attempt to pass `google.auth.default()` credential objects to `gcloud-aio` client constructors.","message":"The `gcloud-aio-auth.Token` class manages credentials specifically for the `gcloud-aio` ecosystem. Its default credential discovery relies on the Google Cloud metadata server, which may not be accessible outside of GCP environments (resulting in 'Name does not resolve' errors like 'Cannot connect to host metadata.google.internal'). For such environments, providing credentials explicitly (e.g., via a `service_file`) is necessary. Additionally, direct interoperability by passing `google.auth.default()` credential objects to `gcloud-aio` clients is not the standard pattern and can lead to issues. Always rely on `gcloud-aio.auth.Token` for authentication within `gcloud-aio` clients.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure `Token` instances are closed. The recommended pattern is `async with Token(...) as token:` or, if not using a context manager, explicitly call `await token.close()` before your application exits.","message":"When creating `Token` instances (or any `gcloud-aio` client that manages an internal `aiohttp.ClientSession`), it is crucial to properly close them to prevent resource leaks. Use them within an `async with` statement or explicitly call `await token.close()` when done.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T20:33:36.198Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure you are using a JSON service account key downloaded from the Google Cloud Console (IAM & Admin -> Service Accounts -> Keys -> Add Key -> Create new key -> JSON), and that this file is correctly passed to `gcloud.aio.auth.Token(service_file=...)`.","cause":"The provided JSON key file is not a valid Google Cloud service account key, or it's incorrectly formatted, missing required fields like 'client_email' or 'token_uri'. This often occurs when using OAuth 2.0 client IDs instead of service account keys.","error":"Error: The incoming JSON object does not contain a client_email field"},{"fix":"Authenticate locally by running `gcloud auth application-default login` in your terminal, or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the absolute path of your service account JSON key file (e.g., `export GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/keyfile.json\"`).","cause":"The `gcloud-aio-auth` library, relying on Application Default Credentials (ADC), cannot find valid credentials in the execution environment. This typically means the `GOOGLE_APPLICATION_CREDENTIALS` environment variable is not set, or `gcloud auth application-default login` has not been run or its credentials are not accessible.","error":"google: could not find default credentials"},{"fix":"Increase the `timeout` parameter when initializing `gcloud.aio.auth.Token` or when making requests, and consider implementing robust retry logic with exponential backoff for network operations.","cause":"An asynchronous operation, often during token acquisition (e.g., in `acquire_access_token`) or an HTTP request made by the internal `gcloud-aio-auth` session, exceeded its allotted time. This can be due to network latency, slow responses from Google's authentication servers, or an overly aggressive timeout setting.","error":"TimeoutError"},{"fix":"Ensure that `google-api-core`, `grpcio`, and all `google-cloud-*` packages are updated to their latest compatible versions or pinned to known stable versions that work well together (e.g., `pip install --upgrade google-api-core grpcio` or, if necessary, pin `google-api-core==1.17.0` as was a past solution for similar issues).","cause":"This `AttributeError` often arises from version incompatibilities between `grpcio`, `google-api-core`, and other `google-cloud-python` client libraries, particularly in asynchronous contexts. While not directly from `gcloud-aio-auth`, it indicates a broader dependency conflict within the async Google Cloud ecosystem.","error":"AttributeError: module 'grpc.experimental.aio' has no attribute 'Call'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.4.4","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"5.4.2","pypi_latest":"5.4.4","is_stale":true,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.6,"mem_mb":15.2,"disk_size":"60.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":15.1,"disk_size":"59.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6.3,"import_time_s":0.4,"mem_mb":15.2,"disk_size":"62M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":15.1,"disk_size":"61M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.71,"mem_mb":16.4,"disk_size":"68.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.9,"mem_mb":16.4,"disk_size":"67.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.5,"import_time_s":0.64,"mem_mb":16.4,"disk_size":"70M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":16.4,"disk_size":"70M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.87,"mem_mb":16.8,"disk_size":"62.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.93,"mem_mb":16.8,"disk_size":"62.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.6,"import_time_s":0.87,"mem_mb":16.8,"disk_size":"65M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.95,"mem_mb":16.8,"disk_size":"64M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.9,"mem_mb":17.1,"disk_size":"62.1M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.96,"mem_mb":17.1,"disk_size":"61.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.8,"import_time_s":0.83,"mem_mb":17.1,"disk_size":"64M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.97,"mem_mb":17.1,"disk_size":"64M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.56,"mem_mb":14.7,"disk_size":"45.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.58,"mem_mb":14.8,"disk_size":"45.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":6.9,"import_time_s":0.52,"mem_mb":14.7,"disk_size":"48M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"gcloud-aio-auth","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.49,"mem_mb":14.8,"disk_size":"48M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}