H2O Python Clients Authentication Helpers

3.1.0 · active · verified Fri Apr 17

h2o-authn provides authentication helpers for H2O.ai Python clients, simplifying secure interactions with H2O AI Cloud and other services. It primarily focuses on managing and refreshing access tokens using various authentication flows, such as Client Credentials. The current version is 3.1.0, and the library maintains an active development pace with several releases per year.

Common errors

```
RuntimeError: Missing environment variable: H2O_AUTHN_CLIENT_ID
```
cause One of the required environment variables (H2O_AUTHN_URI, H2O_AUTHN_CLIENT_ID, H2O_AUTHN_CLIENT_SECRET) for token provider initialization is not set.

fix Set the missing environment variable. For example: `export H2O_AUTHN_CLIENT_ID="your_client_id"`.
```
h2o_authn.auth.token_provider.TokenEndpointError: Authentication request failed (status: 401 Unauthorized)
```
cause The authentication request to the provided `H2O_AUTHN_URI` failed, typically due to incorrect client ID, client secret, or an invalid authentication endpoint.

fix Verify that `H2O_AUTHN_URI`, `H2O_AUTHN_CLIENT_ID`, and `H2O_AUTHN_CLIENT_SECRET` are all correct and correspond to a valid H2O AI Cloud instance or authentication service.
```
ModuleNotFoundError: No module named 'h2o_authn'
```
cause The `h2o-authn` library is not installed in the active Python environment.

fix Install the library using pip: `pip install h2o-authn`.
```
ImportError: cannot import name 'ClientCredentialsTokenProvider' from 'h2o_authn.auth.token_provider'
```
cause Attempting to import a class directly from a submodule when it's exposed at the top-level package or vice versa. The specified class is typically available directly under `h2o_authn`.

fix Import the class directly from the top-level package: `from h2o_authn import ClientCredentialsTokenProvider`.

Warnings

breaking Python 3.8 is no longer officially supported as of version 3.0.0. Projects using `h2o-authn` 3.x or later must run on Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or newer, or pin `h2o-authn<3.0.0` if you must remain on Python 3.8.
breaking The minimum required version of the `httpx` library was updated to `0.23.0` in `h2o-authn` v3.0.0. Older versions of `httpx` may cause dependency conflicts or runtime errors.
Fix: Ensure `httpx>=0.23.0` is installed in your environment. If other dependencies require an older `httpx` version, you may face conflicts requiring careful dependency management or pinning `h2o-authn<3.0.0`.
deprecated Python 3.7 support was dropped in `h2o-authn` v2.0.0. Using this library with Python 3.7 is no longer supported and may lead to installation failures or unexpected behavior.
Fix: Upgrade your Python environment to 3.8 or newer. For `h2o-authn>=3.0.0`, Python 3.9+ is required.
gotcha The library heavily relies on environment variables (`H2O_AUTHN_URI`, `H2O_AUTHN_CLIENT_ID`, `H2O_AUTHN_CLIENT_SECRET`) for configuration. Missing or incorrectly set variables will lead to `RuntimeError` or `TokenEndpointError` at runtime.
Fix: Always ensure the necessary environment variables are set correctly before running applications that use `h2o-authn`. Use `os.environ.get('VAR', '')` for safer access in code.

Install

pip install h2o-authn Install stable version
pip install "h2o-authn[discovery]" Install with discovery feature

Imports

ClientCredentialsTokenProvider

from h2o_authn import ClientCredentialsTokenProvider

AuthCache
```
from h2o_authn import AuthCache
```
TokenEndpointError
wrong:
```
from h2o_authn import TokenEndpointError
```
correct:
```
from h2o_authn.auth.token_provider import TokenEndpointError
```
Commonly nested exceptions are imported from their specific module path.

Quickstart

This quickstart demonstrates how to use `h2o-authn` to obtain an access token using the Client Credentials flow. It fetches authentication details from environment variables (H2O_AUTHN_URI, H2O_AUTHN_CLIENT_ID, H2O_AUTHN_CLIENT_SECRET), initializes a `ClientCredentialsTokenProvider` with an `httpx.AsyncClient`, and then retrieves a token. It also shows wrapping the provider with `AuthCache` for automatic token caching and refreshing.

import os
import httpx
import asyncio
from h2o_authn import ClientCredentialsTokenProvider, AuthCache

async def authenticate_and_get_token():
    auth_url = os.environ.get("H2O_AUTHN_URI", "")
    client_id = os.environ.get("H2O_AUTHN_CLIENT_ID", "")
    client_secret = os.environ.get("H2O_AUTHN_CLIENT_SECRET", "")

    if not all([auth_url, client_id, client_secret]):
        print("Please set H2O_AUTHN_URI, H2O_AUTHN_CLIENT_ID, and H2O_AUTHN_CLIENT_SECRET environment variables.")
        return

    async with httpx.AsyncClient() as client:
        token_provider = ClientCredentialsTokenProvider(
            auth_url=auth_url,
            client_id=client_id,
            client_secret=client_secret,
            client=client,
        )

        # Optional: Wrap with AuthCache for token caching and refresh
        cached_token_provider = AuthCache(token_provider)

        try:
            token = await cached_token_provider.get_token()
            print(f"Successfully obtained token. Access Token (first 10 chars): {token.access_token[:10]}...")
            print(f"Token expires in: {token.expires_in} seconds")
        except Exception as e:
            print(f"Authentication failed: {e}")

if __name__ == "__main__":
    asyncio.run(authenticate_and_get_token())

view raw JSON →