Registry / gcp / gcloud-aio-auth

gcloud-aio-auth

JSON →
library5.5.0pypypi✓ verified 26d ago

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.

pip install gcloud-aio-auth
INSTALL
IMPORT
SIG · GCLOUD-AIO-AUTH
G
gcloud-aio-auth
gcppythonv5.5.0
Install
5.1s avg
Import
698ms
Disk
47MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v5.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.738s · 45.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.1s · import 0.658s · 51MB
47MB installed
● package 47MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Token
from gcloud.aio.auth import Token
Primary class for managing Google Cloud OAuth 2.0 access tokens.
IapToken
from gcloud.aio.auth import IapToken
Class for handling OpenID Connect ID tokens for IAP-secured services.
IamClient
from gcloud.aio.auth import IamClient
Client for interacting with Google Cloud IAM public keys and URL signing.

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.

import asyncio import os import aiohttp from gcloud.aio.auth import Token async def main(): # Attempt to use GOOGLE_APPLICATION_CREDENTIALS environment variable or ADC # For local development, ensure `gcloud auth application-default login` has been run # or GOOGLE_APPLICATION_CREDENTIALS points to a service account key file. service_account_path = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', '') print("Initializing Token...") # Initialize Token; it will try to discover credentials if service_file is None. # Specify necessary scopes for your application. token = Token( service_file=service_account_path if service_account_path else None, scopes=["https://www.googleapis.com/auth/cloud-platform"] ) async with aiohttp.ClientSession() as session: try: # Get an access token (automatically refreshed by the Token instance) access_token = await token.get() print(f"Successfully obtained access token (first 10 chars): {access_token[:10]}...") # Example: Make an authenticated request to a Google Cloud API # (e.g., list buckets in Google Cloud Storage) headers = {"Authorization": f"Bearer {access_token}"} print("Making a dummy authenticated request to Google Cloud Storage API...") async with session.get( "https://www.googleapis.com/storage/v1/projects/_/buckets", headers=headers ) as response: if response.status == 200: print(f"Request to GCS successful (status 200). Some buckets (if any): {await response.json()}") else: print(f"Request failed with status: {response.status}") print(f"Response body: {await response.text()}") except Exception as e: print(f"An error occurred: {e}") finally: # Ensure the token's internal session is closed await token.close() if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingPython 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]
fix
Upgrade Python environment to version 3.10 or later.
affects: >=5.4.4
gotchaThe `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]
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.
affects: <5.4.4
gotchaThe `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.
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.
affects: all
gotchaWhen 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.
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.
affects: all
Errors
Common errors & fixes
Error: The incoming JSON object does not contain a client_email field
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.
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=...)`.
google: could not find default credentials
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.
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"`).
TimeoutError
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.
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.
AttributeError: module 'grpc.experimental.aio' has no attribute 'Call'
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.
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).
Upgrade
Version history
5.5.0latest on PyPI · released Jul 17, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
aiohttprequiredCore dependency for asynchronous HTTP requests.
google-authrequiredUnderlying Google authentication mechanisms.
Agent activity
33 hits · last 30 days
node
28
OpenAI (training)
1
Resources
gcloud-aio-auth — pip install gcloud-aio-auth · libregistry