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 a blueprint deployed to /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.

Source of truth is deploy/authentik/homelab-monitor-oidc.yaml in this repo — the copy on CT121 was hand-edited via scp/pct push several times before this was committed here, meaning CT121 was the only record of the current config for a while. If CT121 is ever rebuilt, redeploy from this file (substituting the real client_secret from Vaultwarden, since Authentik blueprints don't support secret references and the repo copy uses a placeholder):

scp deploy/authentik/homelab-monitor-oidc.yaml pve:/tmp/
ssh pve "pct push 121 /tmp/homelab-monitor-oidc.yaml /opt/authentik/blueprints-local/homelab-monitor-oidc.yaml"
ssh pve "pct exec 121 -- docker restart authentik-worker-1"

• 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.
• property_mappings: the three default Authentik OpenID scope mappings (openid/profile/email) — see "Bug: username field showed a raw session-token-looking hash" below for why this matters.
• invalidation_flow: default-invalidation-flow (full Authentik logout), not the app-scoped default-provider-invalidation-flow — see "Bug: sign out didn't actually sign out of Authentik" below.

To change anything (redirect URI, flow, scopes), edit deploy/authentik/homelab-monitor-oidc.yaml, redeploy via the commands above, and commit the change.

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.

Bug: sign out didn't actually sign out of Authentik

Issue #19's premise. First implementation was spec-compliant OIDC RP-Initiated Logout — redirected through Authentik's end_session_endpoint with correct id_token_hint + post_logout_redirect_uri — but Authentik's default-provider-invalidation-flow (the initial choice) only invalidates this application's session, leaving the underlying Authentik browser cookie valid. A subsequent "Sign in with Authentik" click would silently re-authenticate with no prompt at all — technically correct per spec (RP-Initiated Logout is only supposed to end the requesting client's session), but doesn't satisfy "sign out should sign out of Authentik too."

Fix: switched invalidation_flow to default-invalidation-flow (Authentik's actual full-logout flow, designation Logout vs. the other's Logged out of application). This is a per-provider setting — doesn't change any other app's own logout behavior. Verified the difference with a full Playwright click-through both ways: app-scoped logout → "Sign in with Authentik" silently re-authenticates; full logout → a real Authentik login form ("Welcome to authentik! Login to continue.") is shown.

Bug: username field showed a raw session-token-looking hash

The OAuth2Provider was created without any property_mappings (scope-to-claims mappings) attached. Requesting scope=openid profile email in the authorization request doesn't matter if the provider itself isn't configured to release the corresponding claims — the ID token only ever carried the bare required claims (sub/iss/aud/exp/...), confirmed by decoding a real captured ID token rather than guessing. The app's claim fallback chain (preferred_username ?? email ?? sub, apps/api/src/auth/oidc.ts) landed on the raw sub value — with sub_mode: hashed_user_id, a long hash — which rendered next to the sign-out button looking like a leaked session token.

Fix: attached Authentik's three default OpenID scope mappings (authentik default OAuth Mapping: OpenID 'openid'/'profile'/'email') via property_mappings in the blueprint. preferred_username now populates correctly. No app-code change was needed — the fix belonged entirely on the Authentik provisioning side.

Credentials

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