Typed client library for the authentication routes exposed by py-oidc-auth.

py-oidc-auth-client is a small Python client that authenticates against the routes provided by the companion server side library py-oidc-auth. It helps applications and scripts obtain and refresh access tokens against an auth server that exposes the standard routes (login, token, device).

Key features

• A simple high level helper py_oidc_auth_client.authenticate()

• Authorization code flow with a local browser callback

• Device flow for headless sessions

• Persistent host-aware token storage with py_oidc_auth_client.TokenStore

• Token caching and refresh token support

• Fully typed public API

When to use this library

Use py-oidc-auth-client when you need to:

• call a service protected by bearer tokens issued by your auth server

• perform interactive login in a local session

• run in a headless environment (batch job, remote shell) and still obtain tokens

• reuse cached or refreshed tokens instead of re-authenticating every time

Quick start

High level authenticate function.

The high level helper performs the best available strategy:

1. Use a cached token if it is still valid.

2. Refresh an access token if a refresh token is available.

3. Fall back to an interactive flow (browser or device) if possible.

from py_oidc_auth_client import authenticate

token = authenticate(host="https://auth.example.org")
headers = token["headers"]

Device flow

Directly use device flow logins without fall back to code flow:

import asyncio
from py_oidc_auth_client import Config, DeviceFlow

async def main():
   flow = DeviceFlow(config=Config(host="https://auth.example.org"))
   device = await flow.get_device_code()
   print(device["uri"])
   print(device["user_code"])
   token = await flow.poll(device.device_code, device.interval)
   print(token["headers"])

asyncio.run(main())

Code flow

Use code flow for IDP’s that do not support/allow device flow:

import asyncio
from py_oidc_auth_client import Config, CodeFlow

async def main():
   flow = CodeFlow(config=Config(host="https://auth.example.org"))
   token = await flow.authenticate()
   print(token["headers"])

asyncio.run(main())

Token storage with TokenStore

A single TokenStore can safely hold tokens for multiple hosts because entries are separated by host internally.

from py_oidc_auth_client import TokenStore, authenticate

store = TokenStore(app_name="my-app")
token = authenticate(
    host="https://auth.example.org",
    store=store,
)
print(token["headers"])

Guides and reference

Guides

• Choosing an authentication strategy
• Non interactive environments
• Configuration
• Recipes

API reference

• API reference

Misc

• What’s new
• Code of Conduct

See also

py-oidc-auth (server library)