litestar-keycloak

Keycloak OIDC/OAuth2 authentication plugin for Litestar — token validation, dependency injection, and guards via Litestar's native plugin protocol.

📖 Documentation

Features

• Bearer token validation (header, cookie, or server-side session)
• JWKS caching with automatic key rotation
• Realm/client role and scope guards
• KeycloakUser injection via Litestar DI
• Optional login/callback/logout/refresh routes — SPA (JSON) or server-rendered (session) flow

Installation

uv add litestar-keycloak

Quick start

from litestar import Litestar, get
from litestar_keycloak import KeycloakPlugin, KeycloakConfig, CurrentUser

@get("/me")
async def me(current_user: CurrentUser) -> dict:
    return {"sub": current_user.sub, "roles": current_user.realm_roles}

app = Litestar(
    route_handlers=[me],
    plugins=[KeycloakPlugin(KeycloakConfig(
        server_url="https://keycloak.example.com",
        realm="my-realm",
        client_id="my-app",
    ))],
)

Any route that declares current_user: CurrentUser requires a valid Bearer token.

Guards

from litestar_keycloak import require_roles, require_scopes

@get("/admin", guards=[require_roles("admin")])
async def admin_panel() -> dict: ...

@get("/reports", guards=[require_scopes("reports:read")])
async def reports() -> dict: ...

Documentation

Configuration, guards, OIDC routes, and the SPA / server-rendered flows are covered in the full documentation. A runnable example app with docker-compose is included.

License

MIT