reference RP

examples/rp-reference/README.md

@@ -0,0 +1,114 @@
+# Porchlight OIDC RP — reference implementation
+
+A small, standalone [Relying Party](https://openid.net/specs/openid-connect-core-1_0.html)
+that authenticates users against a running **porchlight** OpenID Provider.
+
+It hand-rolls every OIDC step (no OIDC client library) so the protocol is
+readable. `PyJWT` is used only for the RS256 signature primitive and JWK
+parsing — the OIDC claim checks (`iss` / `aud` / `exp` / `nonce`) are written
+out explicitly in [`oidc_client.py`](./oidc_client.py).
+
+> Not part of porchlight's shipped code. Lives here as a teaching reference and
+> is intentionally left untracked by git.
+
+## What it demonstrates
+
+1. **Discovery** — fetching `/.well-known/openid-configuration`.
+2. **Authorization Code flow with PKCE** (S256), plus `state` and `nonce`.
+3. **Token exchange** using `client_secret_basic` auth.
+4. **ID token verification** — signature via JWKS, then explicit claim checks.
+5. **UserInfo** — calling the endpoint with the access token.
+6. **Refresh** — using the refresh token (requires `offline_access`).
+7. **Logout** — local only. Porchlight exposes no `end_session_endpoint`, so
+   global single-logout at the OP is not possible; see the comment in `app.py`.
+
+## 1. Register this RP in porchlight
+
+Generate a client secret:
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+Add a client to your `porchlight.toml` (paste the secret above):
+
+```toml
+[clients.showcase-rp]
+client_secret = "<paste-generated-secret>"
+redirect_uris = ["http://localhost:9000/callback"]
+response_types = ["code"]
+scope = ["openid", "profile", "email", "offline_access"]
+token_endpoint_auth_method = "client_secret_basic"
+```
+
+Restart porchlight so it picks up the new client.
+
+## 2. Run porchlight (OP) on :8000
+
+From the repo root:
+
+```bash
+OIDC_OP_ISSUER=http://localhost:8000 OIDC_OP_DEBUG=true \
+  OIDC_OP_CONFIG_FILE=porchlight.toml \
+  uv run uvicorn porchlight.app:create_app \
+    --factory --host 127.0.0.1 --port 8000 --reload --reload-dir src
+```
+
+Make sure you have at least one user to log in as (see the porchlight CLI:
+`uv run porchlight initial-admin` / `create-invite`).
+
+## 3. Run this RP on :9000
+
+```bash
+cd examples/rp-reference
+
+# tell the RP the client secret you generated in step 1
+export OIDC_RP_CLIENT_SECRET="<paste-generated-secret>"
+
+uv run --with-requirements <(uv pip compile pyproject.toml 2>/dev/null) \
+  uvicorn app:create_app --factory --port 9000 --reload
+```
+
+Or, more simply, let uv resolve the local project:
+
+```bash
+cd examples/rp-reference
+uv run uvicorn app:create_app --factory --port 9000 --reload
+```
+
+## 4. Walk through the flow
+
+1. Open <http://localhost:9000/>.
+2. Click **Login with Porchlight** → you're redirected to porchlight.
+3. Authenticate and approve the consent screen.
+4. You land back on the result page showing:
+   - the **verified ID token claims**,
+   - the **UserInfo** response,
+   - the **raw token response**.
+5. Click **Refresh tokens** — note the access token changes and the refresh
+   token rotates, but no new `id_token` is issued (porchlight does not re-mint
+   ID tokens on refresh).
+6. Click **Log out** — clears this RP's session only.
+
+## Configuration
+
+All optional; defaults assume localhost. Override with env vars:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `OIDC_RP_ISSUER` | `http://localhost:8000` | porchlight issuer URL |
+| `OIDC_RP_CLIENT_ID` | `showcase-rp` | must match the `porchlight.toml` client |
+| `OIDC_RP_CLIENT_SECRET` | `change-me` | the generated secret |
+| `OIDC_RP_REDIRECT_URI` | `http://localhost:9000/callback` | must match a registered redirect_uri |
+| `OIDC_RP_SCOPE` | `openid profile email offline_access` | requested scopes |
+| `OIDC_RP_SESSION_SECRET` | dev default | signs the RP session cookie (not the OIDC secret) |
+| `OIDC_RP_LEEWAY` | `30` | allowed clock skew (s) for exp/iat |
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `oidc_client.py` | the hand-rolled OIDC steps — start reading here |
+| `app.py` | FastAPI routes + in-memory session handling |
+| `templates.py` | minimal inline HTML |
+| `config.py` | env-var configuration |