Docs: add a browser SPA integration example #31

New issue

Closed

opened 2026-05-25 14:20:20 +00:00 by navicore · 1 comment

navicore commented

2026-05-25 14:20:20 +00:00

Owner

Background

The README's Quick Start walks through a server-side OIDC integration (Forgejo-style: anz client add ... [--secret], server validates tokens). Since anz now supports browser SPAs (cors_allowed_origins, PKCE-only public clients), there's a second integration mode that has no example anywhere in the docs.

Encountered

The navinote PWA was the first browser SPA consumer. Several non-obvious things had to be figured out from source/spec:

Register a public client (no --secret) so PKCE is enforced.
Set cors_allowed_origins = ["https://your-app.example.com"] in anz.toml.
Browser flow: fetch /.well-known/openid-configuration cross-origin (CORS-bound), navigate to /authorize (not a fetch, so no CORS), POST /token cross-origin with code_verifier (CORS-bound), refresh tokens cross-origin.
Audience to validate at the resource server: realm URL, not client_id (see #30).

Proposed

A short section in the README — "Integrating a browser SPA" — covering:

Register a public PKCE client.
Add the SPA's origin to cors_allowed_origins.
~10-line JS/TS sketch of the PKCE auth-code flow (generate verifier, redirect, callback, token exchange, refresh).
Note that the resource server validating ATs should accept the realm URL as aud.

Doesn't have to be exhaustive — pointer to a working reference (e.g. navinote's pwa/src/lib/auth.js) is fine.

Why now

We don't know whether another SPA will integrate soon. If the answer is "no", this is low priority. If the answer is "expected within the year", the README section pays for itself.

## Background The README's Quick Start walks through a server-side OIDC integration (Forgejo-style: `anz client add ... [--secret]`, server validates tokens). Since anz now supports browser SPAs (`cors_allowed_origins`, PKCE-only public clients), there's a second integration mode that has no example anywhere in the docs. ## Encountered The navinote PWA was the first browser SPA consumer. Several non-obvious things had to be figured out from source/spec: - Register a public client (no `--secret`) so PKCE is enforced. - Set `cors_allowed_origins = ["https://your-app.example.com"]` in `anz.toml`. - Browser flow: fetch `/.well-known/openid-configuration` cross-origin (CORS-bound), navigate to `/authorize` (not a fetch, so no CORS), `POST /token` cross-origin with `code_verifier` (CORS-bound), refresh tokens cross-origin. - Audience to validate at the resource server: realm URL, not `client_id` (see #30). ## Proposed A short section in the README — "Integrating a browser SPA" — covering: 1. Register a public PKCE client. 2. Add the SPA's origin to `cors_allowed_origins`. 3. ~10-line JS/TS sketch of the PKCE auth-code flow (generate verifier, redirect, callback, token exchange, refresh). 4. Note that the resource server validating ATs should accept the realm URL as `aud`. Doesn't have to be exhaustive — pointer to a working reference (e.g. navinote's `pwa/src/lib/auth.js`) is fine. ## Why now We don't know whether another SPA will integrate soon. If the answer is "no", this is low priority. If the answer is "expected within the year", the README section pays for itself.

navicore added the

documentation

label

2026-05-25 14:27:19 +00:00

navicore referenced this issue from a commit

2026-05-25 14:47:38 +00:00

● The design is implemented and verified. just ci passes — fmt, clippy (warnings-as-errors), 109 tests, release

navicore referenced this issue

2026-05-25 14:47:46 +00:00

● The design is implemented and verified. just ci passes — fmt, clippy (warnings-as-errors), 109 tests, release #32

navicore commented

2026-05-25 14:48:43 +00:00