Flask API#

Flask integration for py oidc auth.

Flask view functions are synchronous. The base implementation is async, so this adapter uses asyncio.run to call the async methods. The broker verify() call is synchronous and is called directly.

Install:

pip install py-oidc-auth[flask]
conda install -c conda-forge py-oidc-auth-flask

Usage

from flask import Flask
from py_oidc_auth.flask_auth import FlaskOIDCAuth

auth = FlaskOIDCAuth(
    client_id="my client",
    client_secret="secret",
    discovery_url="https://idp.example.org/realms/demo/.well-known/openid-configuration",
    scopes="myscope profile email",
    broker_mode=True,
    broker_store_url="postgresql+asyncpg://user:pw@db/myapp",
)

app = Flask(__name__)
app.register_blueprint(auth.create_auth_blueprint(prefix="/api"))

@app.get("/protected")
@auth.required()
def protected(token):
    return {"sub": token.sub}

class py_oidc_auth.flask_auth.FlaskOIDCAuth(client_id: str = '', discovery_url: str = '', client_secret: str | None = None, scopes: str = 'profile email', audience: str | None = None, appname: str = 'py-oidc-auth', proxy: str = '', claims: Dict[str, Any] | None = None, offline_access: bool = True, timeout_sec: int = 10, jwks_uri: str | None = None, issuer: str | None = None, broker_mode: bool = False, broker_store_url: str | None = None, broker_store_obj: BrokerStore | None = None, broker_audience: str = 'py-oidc-auth', trusted_issuers: list[str] | None = None, broker_jwks_path: str = '/auth/v2/.well-known/jwks.json')#

Reusable OpenID Connect helper for Flask.

The auth endpoints are suitable for browser based login and for programmatic token refresh.

This adapter provides:

required() and optional() decorators for view functions
create_auth_blueprint() to expose a standard set of auth endpoints
When broker_mode=True the decorators verify broker JWTs and the blueprint token endpoints issues broker JWTs instead of passing IDP tokens through.

required(claims: Dict[str, Any] | None = None, scopes: str = '') → Callable[[F], F]#

Enforce authentication.

The decorated view receives the validated IDToken as its first positional argument.

Parameters:

claims – Optional claim constraints.
scopes – Space separated scope names the token must contain.

Returns:

Decorator for Flask views.

Example

@app.get("/admin")
@auth.required(claims={"groups": ["admins"]}, scopes="admin")
def admin(token):
    return {"sub": token.sub}

optional(claims: Dict[str, Any] | None = None, scopes: str = '') → Callable[[F], F]#

Allow anonymous access.

The decorated view receives IDToken or None as its first positional argument.

Parameters:

claims – Optional claim constraints.
scopes – Space separated scope names.

Returns:

Decorator for Flask views.

Example

@app.get("/feed")
@auth.optional()
def feed(token):
    if token:
        return {"message": f"Welcome {token.preferred_username}"}
    return {"message": "Welcome guest"}

create_auth_blueprint(prefix: str = '', login: str | None = '/auth/v2/login', callback: str | None = '/auth/v2/callback', token: str | None = '/auth/v2/token', device_flow: str | None = '/auth/v2/device', logout: str | None = '/auth/v2/logout', userinfo: str | None = '/auth/v2/userinfo', jwks: str | None = '/auth/v2/.well-known/jwks.json') → flask.Blueprint#

Build a Flask flask.Blueprint with standard auth routes.

Each route can be disabled by passing None for its path.

Parameters:

prefix – URL prefix for all routes.
login – Path for login.
callback – Path for callback.
token – Path for token exchange and refresh.
device_flow – Path for starting the device flow.
logout – Path for logout.
userinfo – Path for userinfo.
jwks – Path for the JWKS endpoint (broker mode only).

Returns:

A blueprint ready to be registered on your app.

Raises:

ValueError – When broker_mode=True and token is falsy.

Request examples

GET /auth/v2/login?redirect_uri=https%3A%2F%2Fapp.example.org%2Fcallback HTTP/1.1
Host: app.example.org

POST /auth/v2/token HTTP/1.1
Host: app.example.org
Content-Type: application/x-www-form-urlencoded

refresh_token=ref