eblume/hephaestus
1
0
Fork 0
generated from eblume/project-template
Code Issues Pull requests Projects Releases 10 Packages Wiki Activity Actions

doc(heph-pwa): in-app Authentik login replaces manual token paste

Browse source 
Document the PKCE 'Login with Authentik' flow, the hub /config zero-config
discovery, and the redirect-URI prerequisite on the Authentik heph provider.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erich Blume 2026-06-05 07:09:42 -07:00
commit a0be0f1085
2 changed files with 14 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/changelog.d/heph-pwa-oidc-login.feature.md Normal file
View file

@ -0,0 +1 @@
heph-pwa: added a **Login with Authentik** button — a proper browser OIDC sign-in (Authorization Code + PKCE) that replaces the manual bearer-token paste. The hub exposes an unauthenticated `GET /config` (`{issuer, client_id}`) so the app is zero-config when served from the hub; the PWA discovers the IdP endpoints, runs the PKCE redirect, exchanges the code for a token, and silently refreshes it (`offline_access`). The manual token field remains as a fallback. Requires the PWA origin registered as a redirect URI on the Authentik `heph` provider.

21
docs/how-to/host-heph-pwa.md
View file

@ -95,16 +95,19 @@ app defaults its hub URL to its own origin.
1. Ensure the phone is on the tailnet (or can reach the proxy).
2. Open the hub URL (`https://indri.<tailnet>.ts.net/`) and **Add to Home Screen**.
3. The app defaults its **Hub URL** to the origin it loaded from — no typing.
4. **Token:** the hub requires an OIDC bearer token, and the PWA does **not yet
implement the in-app device-code login** — paste a token into Settings →
Token for now. Obtain one via the device-code flow against the Authentik
client (the same flow the CLI uses; e.g. reuse the access token a logged-in
spoke cached, or run a one-off device-code grant). Tap **Test** to confirm.
4. **Sign in:** open **Settings → Login with Authentik**. The app reads the
hub's `GET /config` for the issuer + client id (zero-config) and runs an
Authorization-Code + PKCE redirect to Authentik; after you approve it lands
back on the app, signed in, and silently refreshes the token from then on.
(A manual **Bearer token** field remains as a fallback for hubs without
OIDC, or for pasting a one-off token.)
> **Known gap / next step:** wire the RFC 8628 device-code flow into the PWA's
> Settings so login is in-app (open the verification URL, poll for the token,
> store it, and refresh it) — removing the manual paste. Tracked as follow-up
> work for `heph-pwa`.
**Prerequisite — register the PWA redirect URI.** Browser PKCE needs the app's
origin registered on the Authentik `heph` provider's **Redirect URIs** (Authentik
also keys token-endpoint CORS off those origins). Add the PWA origin(s) with a
trailing slash, e.g. `https://heph.ops.eblu.me/` (and `http://localhost:8787/`
for local dev). In blumeops this is the `redirect_uris` list on the heph
provider blueprint.
## Upgrades