homelab-monitor/docs/oidc-setup.md

Authentik OIDC setup

Local auth (bcrypt + session, the saved Vaultwarden password) is always available. When OIDC_ENABLED=true, the login page additionally shows a "Sign in with Authentik" button — this is additive, not a replacement, so the existing admin login keeps working.

How the Authentik side was provisioned

No API token or admin credentials were needed. Authentik supports blueprints — declarative YAML files it applies automatically — so the OAuth2 Provider + Application were created via /opt/authentik/blueprints-local/homelab-monitor-oidc.yaml on CT121, picked up by the worker container on startup. This is purely additive: it doesn't touch any existing user, group, or admin credential.

• Blueprint volume mount added to /opt/authentik/docker-compose.yml (backed up as docker-compose.yml.bak-homelab-monitor before editing) for both server and worker.
• Provider: confidential client, default-provider-authorization-implicit-consent flow (auto-approve — reasonable for a single-user personal dashboard), signed with Authentik's existing self-signed cert.
• Redirect URIs (both registered): https://monitor.jerodrigged.com/api/auth/oidc/callback (primary, set in .env) and http://192.168.1.103:8090/api/auth/oidc/callback (LAN fallback, works if the tunnel/DNS is down).
• Application slug: homelab-monitor.

To change anything (redirect URI, flow, scopes), edit the blueprint file on CT121 and either wait for Authentik's file-watcher or docker restart authentik-worker-1 — it re-applies on any change to the file.

Bug: LAN-IP issuer sent browsers somewhere they couldn't reach

First deploy used OIDC_ISSUER_URL=https://192.168.1.208:9443/application/o/homelab-monitor/ (Authentik's LAN IP) for discovery. Authentik's discovery document echoes back whichever host you queried it through — so authorization_endpoint came back as that same LAN IP. That value gets handed straight to the browser as a redirect target. Anyone off the LAN (or just not on wifi) got redirected to an address they couldn't reach at all — reported as "signed in via Authentik, got sent to the local IP, and it failed."

Fix: Authentik was already publicly exposed at https://auth.jerodrigged.com (NPM proxy host id 9, predates this project) with a real Let's Encrypt cert — just wasn't the one used for OIDC_ISSUER_URL. Switched to it; OIDC_ALLOW_INSECURE_TLS could then go back to false too, since it's not a self-signed cert. Always use the public issuer URL for anything a browser is ever redirected through, even though the app's own server-to-server calls (token exchange, userinfo, jwks — all made directly by the Node process, never by a browser) would have worked fine against the LAN IP too.

API-side implementation

apps/api/src/auth/oidc.ts uses openid-client v6 with PKCE + state, with an optional insecure-TLS fetch override (OIDC_ALLOW_INSECURE_TLS) for the rare case the issuer is LAN-only with a self-signed cert — not needed now that the issuer is the public URL, but kept since Authentik's LAN address still works as a fallback if auth.jerodrigged.com is ever unreachable. Routes in apps/api/src/routes/oidc.ts:

• GET /api/auth/oidc/login — redirects to Authentik's authorization endpoint
• GET /api/auth/oidc/callback — exchanges the code, sets req.session.username from the preferred_username (falls back to email, then sub) ID token claim, and stores authMethod: "oidc" + the raw id_token in the session
• GET /api/auth/oidc/logout — RP-Initiated Logout (issue #19). Only takes this path if req.session.authMethod === "oidc" (a locally-authenticated session has no Authentik session to end); redirects through Authentik's end_session_endpoint with id_token_hint + post_logout_redirect_uri (via openid-client's buildEndSessionUrl, not hand-rolled) before landing back on /. Must be a full-page navigation, not a fetch — the frontend does window.location.href = ..., since Authentik needs to see a real browser request to clear its own session cookie on auth.jerodrigged.com. Plain POST /api/auth/logout still exists for local sessions and just clears the local one.

Authentik has no dedicated post_logout_redirect_uri allowlist field (unlike redirect_uris) as of the version this was built against — confirmed by checking the provider's DB schema (\d authentik_providers_oauth2_oauth2provider) before implementing, not assumed.

Credentials

OIDC_CLIENT_ID/OIDC_CLIENT_SECRET are in CT122's .env and saved in Vaultwarden alongside the local admin login.