ADR 0013: Single sign-on with OpenID Connect and trusted proxy headers¶
- Status: Accepted
- Date: 2026-11-11
- Supersedes: the "no OAuth" consequence of ADR 0005
Context¶
Many home labs already run an identity provider (Authelia, Authentik, Keycloak, Pocket ID) with one login and one second factor for all services (#79). A separate password for the start page is friction, and users ask to manage access centrally.
Decision¶
Two optional ways to prove the owner's identity; both end in the normal session creation, so cookies, CSRF protection, the guard and the session overview stay unchanged:
- OpenID Connect (authorization code flow with PKCE S256,
statebound to the browser in a short-lived cookie,noncein the ID token). Only subjects or verified e-mail addresses listed inOIDC_ALLOWED_SUBJECTS/OIDC_ALLOWED_EMAILSare accepted. - Trusted proxy header (forward auth): the user name in
AUTH_PROXY_HEADER(e.g.Remote-User) is believed only when the TCP peer is inTRUSTED_PROXIES; from every other source it is ignored. Only names inAUTH_PROXY_USERSsign in.
The local second factor is skipped for SSO by default (the identity
provider is responsible); SSO_REQUIRE_2FA=true asks for it anyway.
PASSWORD_LOGIN=false disables the owner's password login once SSO works;
waylight reset-account still recovers. Guests keep their passwords.
Own implementation instead of a library. internal/platform/oidc
implements discovery, PKCE, the token request and ID token validation with
the standard library (~350 lines): RS256 and ES256 only (no none, no HMAC
with public keys), issuer, audience, expiry, issue time, nonce, JWKS cache
with refresh for key rotation. The common libraries (coreos/go-oidc +
golang.org/x/oauth2 + go-jose) would add three dependencies for the
same checks (ADR 0011). The validation is covered by tests against an
in-process provider, including tampered claims, alg: none, wrong
audience/nonce/issuer and expired tokens.
Consequences¶
- No new runtime dependency; the binary stays within its budget.
- We maintain security-relevant code ourselves: the tests above are the safety net, and the scope is deliberately small (no implicit flow, no refresh tokens, no userinfo endpoint, no logout propagation).
- Header auth is only safe behind a proxy that strips the header from
clients;
docs/reverse-proxy.mdshows Authelia and Authentik setups.