h2o-authn

H2O Python Clients Authentication Helpers.

Installation

pip install h2o-authn

Usage

Package provides two top level classes h2o_authn.TokenProvider and h2o_authn.AsyncTokenProvider with identical constructors accepting following arguments:

• refresh_token: Refresh token which will be used for the access token exchange.
• client_id: OAuth 2.0 client id that will be used for the access token exchange.
• issuer_url or token_endpoint_url needs to be provided
  • issuer_url: Base URL of the issuer. This URL will be used for the discovery to obtain the token endpoint. Mutually exclusive with the token_endpoint_url argument.
  • token_endpoint_url: URL of the token endpoint that should be used for the access token exchange. Mutually exclusive with the issuer_url argument. If not provided explicitly, the value of the H2O_CLOUD_TOKEN_ENDPOINT_URL environment variable is used if set.
• client_secret: Optional OAuth 2.0 client secret for the confidential clients. Used only when provided.
• scope: Optionally sets the scope for which the access token should be requested.
• expiry_threshold: How long before token expiration should the token be refreshed when needed. This does not mean that the token will be refreshed before it expires, but only indicates the earliest moment before the expiration when refresh would occur. (default: 5s)
• expires_in_fallback: Fallback value for the expires_in value. Will be used when the token response does not contain the expires_in field.
• minimal_refresh_period: Optionally, the minimal period between the earliest token refresh exchanges.

Both classes have an identical interface in sync and async variants.

provider = h2o_authn.TokenProvider(...)
aprovider = h2o_authn.AsyncTokenProvider(...)


# Calling the providers directly makes sure that a fresh access token is available
# and returns it.
access_token = provider()
access_token = await aprovider()


# Calling the token() returns h2o_authn.token.Token instance.
token = provider.token()
token = await aprovider.token()

# It can be used as a str.
assert token == access_token

# And contains additional attributes when available.
token.exp  # Is expiration of the token as datetime.datetime
token.scope  # Is scope of the token if the server provided it.


# Sync/Async variants can be converted from one to another.
provider = aprovider.as_sync()
aprovider = provider.as_async()


# When an access token with a different scope is needed, a new instance can be cloned from
# the current with a different scope.
provider = provider.with_scope("new scopes")
aprovider = aprovider.with_scope("new scopes")

Examples

Example: Use with H2O.ai MLOps Python CLient

import h2o_authn
import h2o_mlops_client as mlops

provider = h2o_authn.TokenProvider(...)
mlops_client = mlops.Client(
    gateway_url="https://mlops-api.cloud.h2o.ai", token_provider=provider
)
...

Example: Use with H2O.ai Drive Python Client within the Wave App

import h2o_authn
import h2o_drive
from h2o_wave import Q, app, ui
from h2o_wave import main


@app("/")
async def serve(q: Q):
    provider = h2o_authn.AsyncTokenProvider(
        refresh_token=q.auth.refresh_token,
        issuer_url=os.getenv("H2O_WAVE_OIDC_PROVIDER_URL"),
        client_id=os.getenv("H2O_WAVE_OIDC_CLIENT_ID"),
        client_secret=os.getenv("H2O_WAVE_OIDC_CLIENT_SECRET"),
    )
    my_home = await h2o_drive.MyHome(token=provider)

    ...

Example: Use with H2O.ai Enterprise Steam Python Client

import h2o_authn
import h2osteam
import h2osteam.clients

provider = h2o_authn.TokenProvider(...)

h2osteam.login(url="https://steam.cloud-dev.h2o.ai", access_token=provider())
client = h2osteam.clients.DriverlessClient()

...

H2O Cloud Discovery support

If you use the token provider to access H2O.ai services running in your H2O AI Cloud environment, you can simplify the configuration by using h2o-authn[discovery] extension.

For more info regarding H2O Cloud Discovery, please see H2O Cloud Discovery Client

pip install h2o-authn[discovery]

Module h2o_authn.discovery provides new and new_async functions which accepts following arguments:

• discovery: The Discovery object to use for configuration.
• client: The name of the client to use for configuration. Defaults to "platform".
• scope: The scope to use for the token requests.
• expiry_threshold: How long before token expiration should the token be refreshed when needed. This does not mean that the token will be refreshed before it expires, but only indicates the earliest moment before the expiration when refresh would occur. (default: 5s)
• expires_in_fallback: Fallback value for the expires_in value. Will be used when the token response does not contain the expires_in field.
• minimal_refresh_period: Optionally, the minimal period between the earliest token refresh exchanges.

Example: Use of the H2O Cloud Discovery with H2O.ai MLOps Python CLient

import h2o_authn.discovery
import h2o_discovery
import h2o_mlops_client as mlops


discovery = h2o_discovery.discover()

provider = h2o_authn.discovery.create(discovery)

mlops_client = mlops.Client(
    gateway_url=discovery.services["mlops-api"].uri, token_provider=provider
)
...

Development

See RELEASE.md for instructions on how to build and release.