oidc-jwt-verifier 0.1.6

Shared, hardened JWT verification core for OIDC/JWKS issuers

oidc-jwt-verifier

oidc-jwt-verifier is a small, framework-agnostic JWT verification core for OIDC/JWKS issuers.

It provides:

• A hardened sync verifier (JWTVerifier)
• A native async verifier (AsyncJWTVerifier)
• Public JWKS lifecycle/readiness APIs on both sync and async clients
• First-party FastAPI and Starlette integration helpers

Install

pip install oidc-jwt-verifier

For async/FastAPI/Starlette support:

pip install "oidc-jwt-verifier[async]"
pip install "oidc-jwt-verifier[fastapi]"
pip install "oidc-jwt-verifier[starlette]"

For development:

uv pip install -e ".[dev]"

Quickstart

from oidc_jwt_verifier import AuthConfig, JWTVerifier

config = AuthConfig(
    issuer="https://example-issuer/",
    audience="https://example-api",
    jwks_url="https://example-issuer/.well-known/jwks.json",
    allowed_algs=("RS256",),
    required_scopes=("read:users",),
)

verifier = JWTVerifier(config)
claims = verifier.verify_access_token(token)

Async quickstart

from oidc_jwt_verifier import AuthConfig
from oidc_jwt_verifier.async_verifier import AsyncJWTVerifier

config = AuthConfig(
    issuer="https://example-issuer/",
    audience="https://example-api",
    jwks_url="https://example-issuer/.well-known/jwks.json",
    allowed_algs=("RS256",),
)

async def verify(token: str) -> dict[str, object]:
    async with AsyncJWTVerifier(config) as verifier:
        return await verifier.verify_access_token(token)

JWKS lifecycle and readiness

Use the verifier-level helpers for startup validation and cache priming:

from oidc_jwt_verifier import AuthConfig, JWTVerifier

config = AuthConfig(
    issuer="https://example-issuer/",
    audience="https://example-api",
    jwks_url="https://example-issuer/.well-known/jwks.json",
)

verifier = JWTVerifier(config)
if not verifier.healthcheck(refresh=True):
    raise RuntimeError("JWKS endpoint is not ready")

signing_keys = verifier.get_signing_keys()

If you need direct client access, use JWKSClient or AsyncJWKSClient from oidc_jwt_verifier.jwks and oidc_jwt_verifier.async_jwks. The sync and async lifecycle/readiness APIs are intentionally parallel public surfaces.

These are startup/readiness APIs. Do not call them on every request.

FastAPI integration

from fastapi import Depends, FastAPI
from oidc_jwt_verifier import AuthConfig
from oidc_jwt_verifier.async_verifier import AsyncJWTVerifier
from oidc_jwt_verifier.integrations.fastapi import create_async_bearer_dependency

app = FastAPI()
verifier = AsyncJWTVerifier(
    AuthConfig(
        issuer="https://example-issuer/",
        audience="https://example-api",
        jwks_url="https://example-issuer/.well-known/jwks.json",
    )
)
auth = create_async_bearer_dependency(verifier, realm="api")

@app.get("/protected")
async def protected(claims: dict = Depends(auth)):
    return {"sub": claims.get("sub")}

Starlette integration

from starlette.applications import Starlette
from starlette.requests import Request
from starlette.responses import JSONResponse
from starlette.routing import Route

from oidc_jwt_verifier.integrations.starlette import BearerAuthMiddleware

async def protected(request: Request) -> JSONResponse:
    claims = request.state.auth_claims
    return JSONResponse({"sub": claims.get("sub")})

app = Starlette(routes=[Route("/protected", protected)])
app.add_middleware(BearerAuthMiddleware, verifier=verifier, realm="api")

Secure-by-default behavior

The verifier:

• Verifies signature, iss, aud, exp, and nbf (when present).
• Uses an explicit algorithm allowlist and rejects alg=none.
• Enforces minimum cryptographic key lengths by default (configurable via enforce_minimum_key_length).
• Fails closed on malformed tokens, JWKS fetch errors, timeouts, missing keys, and missing kid.
• Never derives a JWKS URL from token headers, and rejects tokens that include jku, x5u, or crit.
• Supports Auth0-style multi-audience tokens (aud as an array) and enforces required scopes and permissions.

Auth0 guidance for API token validation calls out validating the JWT and then checking aud and scopes in the scope claim. See the Auth0 docs for details.

Error handling

The public exception type is AuthError.

AuthError carries:

• code: stable, machine-readable reason
• status_code: 401 (authentication) or 403 (authorization)
• www_authenticate_header(): an RFC 6750 compatible WWW-Authenticate value for Bearer auth

from oidc_jwt_verifier import AuthError

try:
    claims = verifier.verify_access_token(token)
except AuthError as err:
    status = err.status_code
    www_authenticate = err.www_authenticate_header()

Why this library

JWT verification for APIs is easy to get mostly right while still missing important security and interoperability details. This library is a small, framework-agnostic core that centralizes conservative verification policy (claims, algorithms, header handling) and authorization checks (scopes/permissions) so you can reuse it across projects.

For comparisons against common alternatives (PyJWT directly, discovery-driven verifiers, framework integrations), see docs/alternatives.md.

Documentation

Primary docs are built with MkDocs in docs/.

• Getting started: docs/getting-started.md
• Sync usage: docs/usage/sync.md
• Async usage: docs/usage/async.md
• FastAPI integration: docs/integrations/fastapi.md
• Starlette integration: docs/integrations/starlette.md
• Configuration and security: docs/configuration.md, docs/security.md
• API reference: docs/reference.md
• Migration guidance: docs/migration.md

Contributing

Use Conventional Commits.
Release-specific commit guidance for maintainers is documented in AGENTS.md.

References

• Auth0: Validate Access Tokens: https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens
• Auth0: Validate JSON Web Tokens: https://auth0.com/docs/secure/tokens/json-web-tokens/validate-json-web-tokens
• RFC 8725: JSON Web Token Best Current Practices: https://datatracker.ietf.org/doc/html/rfc8725
• RFC 9700: Best Current Practice for OAuth 2.0 Security: https://www.rfc-editor.org/info/rfc9700
• PyJWT docs and examples: https://pyjwt.readthedocs.io/en/stable/usage.html