Skip to content

oidc-jwt-verifier

A small, framework-agnostic JWT verification core for OIDC/JWKS issuers.

oidc-jwt-verifier is designed to be shared by higher-level adapters (Dash, Bottle, Lambda, FastAPI) while keeping security decisions centralized and consistent.

Installation

pip install oidc-jwt-verifier

For development with documentation tools:

pip install oidc-jwt-verifier[docs]

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)

Secure-by-default behavior

The verifier:

  • Verifies signature, iss, aud, exp, and nbf (when present).
  • Uses an explicit algorithm allowlist and rejects alg=none.
  • 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.

Why this library

This project focuses on making server-side access token verification reproducible across multiple apps and frameworks by centralizing conservative verification and authorization policy.

If you’re deciding between this library and other JWT/OIDC tooling, see Alternatives and rationale.

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()

References