Metadata-Version: 2.5
Name: oauth2-debugger
Version: 0.0.1
Summary: Local debugger for the OAuth2/OIDC Authorization Code flow (state, scopes, PKCE)
Project-URL: Homepage, https://github.com/Shawyeok/oauth2-debugger
Project-URL: Repository, https://github.com/Shawyeok/oauth2-debugger
Author-email: Yike Xiao <kmter@live.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.9
Provides-Extra: verify
Requires-Dist: cryptography>=41; extra == 'verify'
Description-Content-Type: text/markdown

# 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

```bash
uvx oauth2-debugger
```

Or from a checkout:

```bash
cd oauth2-debugger
uv run oauth2-debugger
```

Or without `uv`:

```bash
pip install -e .
oauth2-debugger
```

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

```bash
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.
