oauth2-debugger

A small, dependency-free local web app for manually driving an OAuth2/OIDC Authorization Code (+ PKCE) flow end-to-end against a real authorization server. Client ID, scope, issuer, and PKCE method are all configured on the page itself — no flags to memorize for a one-off test.

A generic RFC 6749 / RFC 7636 client — point it at any OIDC-compliant authorization server via --issuer (or fill it in on the page itself).

Quick start

uvx oauth2-debugger

Or from a checkout:

cd oauth2-debugger
uv run oauth2-debugger

Or without uv:

pip install -e .
oauth2-debugger

Or straight from the source tree with plain stdlib Python, no install:

python3 -m oauth2_debugger

This opens http://127.0.0.1:<port>/ in your browser (an OS-assigned ephemeral port by default — printed to the console either way). Fill in the client_id and scope, click Start Authorization, approve consent if prompted, and you land back on the same page with the full token response and decoded/verified claims.

What it does

1. Form page (GET /): issuer, client_id, scope, PKCE method, endpoint overrides, extra authorize-request params — all editable, pre-filled from whatever you ran last (and from the --client-id/--scope/etc. CLI flags on first load).
2. POST /start: discovers the authorize/token/jwks endpoints from <issuer>/.well-known/openid-configuration (unless you filled in the endpoint overrides), generates a random state and a PKCE verifier/challenge pair, remembers them server-side keyed by state, and 302s your browser to the real authorization server.
3. The redirect_uri is always http://127.0.0.1:<this server's port>/callback — this relies on the authorization server implementing RFC 8252 §7.3 loopback redirect matching (any port accepted as long as host + path match what's registered; Spring Authorization Server does this). So the registered client only ever needs http://127.0.0.1/callback on file, regardless of which port this tool happens to bind on a given run.
4. You approve consent (or it's skipped if already granted for that client+account+scope set) and land back on GET /callback, which validates the returned state against what was stored for it (rejects unknown/reused/ expired state — pending flows are kept for 15 minutes), extracts code, and exchanges it at the token endpoint (with code_verifier if PKCE is enabled).
5. Results page: full token response JSON, each of access_token/id_token decoded and displayed with a copy button, and — if "verify JWT signatures" is on — an inline PASS/FAIL badge from checking the RS256 signature against the issuer's published JWKS. refresh_token gets its own copy button too.

CLI flags (seed the form / control the local server)

--host HOST                     default: 127.0.0.1
--port N                        default: 0 (OS-assigned ephemeral, to avoid
                                 colliding with whatever else is running on your
                                 machine; pass a fixed port for a bookmarkable URL)
--issuer URL                    default: https://auth.example.com
--client-id ID                  default form value (still editable on the page)
--scope "a b c"                 default form value (default: openid)
--pkce-method S256|plain|none   default form value (default: S256)
--no-verify-jwks                default the verify-signature toggle to off
--no-browser                    don't auto-open the form page

Registering a test client

Point --issuer at your own authorization server and register a public (no client secret), loopback-redirect client against it:

redirect_uris:  http://127.0.0.1/callback   (any port accepted per RFC 8252,
                                              if your server supports it)
auth method:    none (public client, PKCE required)
grant types:    authorization_code, refresh_token

Consult your authorization server's own docs for how to register a client — that part is intentionally out of scope for this generic debugging tool.