From a0be0f10856dc07935a2837e2e7efe777f98248f Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Fri, 5 Jun 2026 07:09:42 -0700 Subject: [PATCH] doc(heph-pwa): in-app Authentik login replaces manual token paste 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) --- .../heph-pwa-oidc-login.feature.md | 1 + docs/how-to/host-heph-pwa.md | 21 +++++++++++-------- 2 files changed, 13 insertions(+), 9 deletions(-) create mode 100644 docs/changelog.d/heph-pwa-oidc-login.feature.md diff --git a/docs/changelog.d/heph-pwa-oidc-login.feature.md b/docs/changelog.d/heph-pwa-oidc-login.feature.md new file mode 100644 index 0000000..aae9d26 --- /dev/null +++ b/docs/changelog.d/heph-pwa-oidc-login.feature.md @@ -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. diff --git a/docs/how-to/host-heph-pwa.md b/docs/how-to/host-heph-pwa.md index 0be1d59..63b3d76 100644 --- a/docs/how-to/host-heph-pwa.md +++ b/docs/how-to/host-heph-pwa.md @@ -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..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