Files
Homelab-manager/docs/SSO.md
T
bobbanandClaude Sonnet 5.5 c2e76262ca Documentation: guides in docs/, and the reference docs brought up to date
- New docs/ folder: SSO, API, Prometheus and Grafana, webhooks, heartbeats and calendar, how monitoring works, and an index; the old root API.md is split across them
- Read API: alerts carry snoozedUntil
- DATABASE.md: table and migration counts, indexes, relations, integration config, settings and internal flags, delete rules, retention
- ROLES.md: the sidebar table rebuilt from the menu
- NOTIFICATIONS.md, INTEGRATIONS.md, BACKUP.md, AGENT_UPDATE.md: what had drifted
- README: links to the guides; accounts cannot be deleted in the app

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 00:09:43 +02:00

17 KiB

Single sign-on (SSO)

Homelab Manager has no passwords of its own. People sign in through an identity provider with OpenID Connect (OIDC), and the app only ever sees who they are, never a password. It is written for Authentik and the settings are named after it; any provider that speaks standard OIDC can work (see Other identity providers), but only Authentik has been used.

This page covers what the setup needs, how to configure Authentik and the app, how roles are decided, and what to check when sign-in fails.

How sign-in works

  1. A person opens the app and is sent to /auth/login. The app starts an authorization code flow with PKCE (a one-time code verifier and challenge) and a random state, and redirects the browser to Authentik.
  2. The person signs in at Authentik (with whatever Authentik asks for: password, passkey, two-factor …).
  3. Authentik sends the browser back to <APP_BASE_URL>/auth/callback with a one-time code.
  4. The app, from its own server, swaps the code for tokens at Authentik, checks the ID token's signature against the keys Authentik publishes (not only its contents), and asks Authentik's userinfo address for the person's name, email, picture and groups.
  5. The app finds the person by their sub (Authentik's stable id for them) or makes an account, decides their role (below), writes the sign-in to the audit log and starts a session with a new session id.

The client is confidential: the app holds a client secret, and the code exchange happens server to server. The scopes asked for are openid email profile.

What you need before you start

You need Why
An Authentik instance The identity provider.
The app reachable by browsers at a fixed address — APP_BASE_URL — and over HTTPS in production The redirect address Authentik sends people back to is built from it. The session cookie is marked Secure when the app runs in production (NODE_ENV=production, which the supplied Docker setup does), and browsers only keep a Secure cookie from an HTTPS page — so behind plain http:// on a LAN address, sign-in appears to work and then sends you straight back to the login page. (http://localhost is the exception browsers allow.) Put the app behind a reverse proxy with a certificate.
A reverse proxy that passes X-Forwarded-For and X-Forwarded-Proto (one proxy in front) The app trusts one proxy hop, so the sign-in log and the rate limit see each person's address instead of the proxy's.
The app able to reach Authentik, server to server It calls Authentik's discovery, token, userinfo and key (JWKS) addresses itself, from wherever it runs — from inside the Docker network that may not be the name your browser uses.
Authentik's certificate trusted by the app If Authentik uses a certificate from your own CA, give Node the CA with NODE_EXTRA_CA_CERTS=/path/to/ca.pem. Do not switch certificate checking off with NODE_TLS_REJECT_UNAUTHORIZED=0.
Reasonably correct clocks on both machines Tokens have times in them; a minute of drift is tolerated, more is refused.
Two secrets generated by you SESSION_SECRET (signs the session cookie) and CREDENTIALS_ENCRYPTION_KEY (encrypts stored integration credentials). Not part of SSO itself, but the app will not run in production without the first.

Generate both with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

1. Set up Authentik

The names of the menus differ a little between Authentik versions; what has to be true does not.

Create the provider — Applications → Providers → Create → OAuth2/OpenID Provider:

Setting Value
Name anything, e.g. Homelab Manager
Authorization flow your usual one (explicit or implicit consent, as you prefer)
Client type Confidential
Client ID / Client secret generated for you — you will copy both into the app's .env
Redirect URIs https://hm.example.lan/auth/callback — your APP_BASE_URL followed by /auth/callback, as an exact (strict) match
Signing key choose a certificate (an RSA key), such as authentik Self-signed Certificate. With no signing key Authentik signs ID tokens with the client secret (HS256) and publishes no keys, and the app refuses such a token.
Scopes openid, email, profile (the defaults)
Subject mode leave the default (Based on the hashed User ID) — see the warning below
Issuer mode leave the default (Each provider has a different issuer)

Do not change the subject mode later. The app recognises a person by their sub. Changing how Authentik builds it makes every person a new person: a new account (a viewer, with none of the old account's role) and the old one left behind.

Create the application — Applications → Applications → Create: give it a name and a slug (e.g. homelab-manager), choose the provider above, and decide who may use it (a policy or group binding on the application). Authentik decides who can sign in; the app's roles decide what they can do once in.

The issuer URL you need next is on the provider's page — normally https://authentik.example.lan/application/o/<slug>/, with the trailing slash.

2. Set up the app

Put these in the .env file next to docker-compose.yml (a template is in .env.example):

# Where people reach the app. HTTPS, no trailing slash needed. Used to build the redirect address.
APP_BASE_URL=https://hm.example.lan

# From the Authentik provider.
AUTHENTIK_ISSUER_URL=https://authentik.example.lan/application/o/homelab-manager/
AUTHENTIK_CLIENT_ID=…
AUTHENTIK_CLIENT_SECRET=…

# Generated by you (see above). Changing SESSION_SECRET signs everyone out.
SESSION_SECRET=…
CREDENTIALS_ENCRYPTION_KEY=…
Variable Meaning
APP_BASE_URL The address people type. The redirect address is APP_BASE_URL + /auth/callback; it must match what the Authentik provider allows, character for character (scheme, host, port). Also the address used in links in notifications and in the read API.
AUTHENTIK_ISSUER_URL The provider's issuer URL. The app discovers the rest from <issuer>/.well-known/openid-configuration, so a wrong or unreachable issuer is the usual reason sign-in fails.
AUTHENTIK_CLIENT_ID, AUTHENTIK_CLIENT_SECRET From the provider. The secret is read from the environment only; it is not stored in the database.
SESSION_SECRET Signs the session cookie. In production the app refuses to start without it, and warns if it is still the placeholder from .env.example or shorter than 32 characters.
SESSION_DIR Where sessions are kept on disk (default data/sessions, inside the data volume).
NODE_ENV production in the Docker image: makes the cookie Secure and requires SESSION_SECRET.

If any of the three AUTHENTIK_* values is missing the app still starts — so the rest of it can be looked at — but /auth/login fails until they are set. Restart the container after changing .env.

3. The first sign-in

The first person to sign in becomes the administrator, so sign in yourself first on a new installation. Everyone after that starts as a viewer until an administrator changes their role under Administration → Users — or until their groups decide it (below).

Only people Authentik lets into the application can sign in at all, which is why the application's access policy matters: the first account is whoever you let in first.

Roles

There are three: viewer (sees everything, changes nothing), operator (acknowledges and silences alerts, starts maintenance, runs updates, writes notes and jobs …) and admin (everything, including settings, integrations and users). ROLES.md lists exactly who can see and do what.

By hand (the default)

Administrators change roles on Administration → Users. The only administrator cannot be demoted — there is always at least one.

From groups

Instead of setting roles by hand, let the groups Authentik reports decide them. In Authentik, the user's groups come in a groups claim that is part of the profile scope the app already asks for, so there is nothing to add on the Authentik side except the groups themselves (e.g. homelab-admins, homelab-ops) and who is in them.

In the app: Settings → Sign-in → Roles from groups.

Setting Meaning
Set roles from groups at each sign-in The switch. Off, roles are by hand.
Claim that holds the groups groups for Authentik.
Admin groups Names (one per line or comma separated; case does not matter). In any of them → admin.
Operator groups In any of them (and in no admin group) → operator.
Someone in none of those groups becomes a viewer, or keeps the role they already have.

The rules are applied at every sign-in, so a change in Authentik shows up the next time the person signs in (or when their session next starts), not instantly.

Safeguards:

  • If a sign-in carries no groups claim at all (a wrong claim name, a scope that is missing), roles are left exactly as they are — "we weren't told" is never treated as "in no groups".
  • The only administrator is never demoted by a group rule.
  • The first person to sign in is still the administrator, whatever the groups say.
  • While roles follow groups, roles cannot be set by hand (a role set on the Users page would be undone at the next sign-in); the Users page says so.
  • Every role change made from groups is written to the audit log (user / role_from_groups, and role_from_groups_blocked when the last administrator was protected).

Before switching it on, press Check against the groups people had last time: it changes nothing and shows what each person would become, from the groups they had at their last sign-in. The groups each person had are also shown on the Users page, so you can see the names before relying on them.

Profile pictures

Optional, off by default (Settings → Sign-in → Profile pictures): the picture Authentik gives, and/or a Gravatar. Either one means the server fetches the picture from an outside address; people's browsers never do, and the app serves the pictures from itself.

Sessions and signing out

  • A session lasts up to 7 days. The cookie is HttpOnly, SameSite=Lax and, in production, Secure.
  • Disabling someone in Authentik does not end an app session that is already running. To cut someone off at once, end their session under Users → Signed in now (administrators); it ends immediately, and they cannot start another once Authentik refuses them. Accounts themselves are not deleted in the app — a person who no longer signs in simply has no session.
  • Signing out of the app also ends the person's Authentik session when Authentik supports RP-initiated logout (it does), so the next visit asks for a password again. Ending a session from Signed in now ends only the app's own session, not the one at Authentik.
  • Sign-ins and sign-outs are in the audit log, with the address they came from.

What does not use SSO

Some addresses are meant for machines and use their own tokens instead of a session. None of them can be used to sign in, and each stops working the moment its token is removed.

Address Used by Token
/api/agent/report the agent on each server one per server, shown once when the server is added
/metrics Prometheus a metrics token (Settings → API and webhooks) — see PROMETHEUS-GRAFANA.md
/api/v1/… scripts, Home Assistant a personal API token (user menu → API tokens) — see API.md
/api/heartbeat/<token> cron jobs the heartbeat's own address — see HEARTBEATS-AND-CALENDAR.md
/api/public/… status pages, the wall display, the calendar feed a share link (Settings → Share links)
/health container health checks none (answers {"ok":true})

Troubleshooting

A failed sign-in shows a plain page ("Sign-in failed") and nothing more — deliberately, since the reason would tell an attacker what to adjust. The reason is in the server log and in the audit log (Change log → Raw audit log, category session, action login_failed, with the address and a short reason).

Reason in the log What it usually means
provider_unreachable The app could not reach Authentik to read its configuration: a wrong AUTHENTIK_ISSUER_URL (missing trailing slash, wrong slug, http instead of https), a name the container cannot resolve, a firewall, or a certificate the app does not trust (see NODE_EXTRA_CA_CERTS). It retries on the next sign-in; no restart is needed.
provider_rejected Authentik answered but the exchange failed. Most often: the redirect URI in the provider is not exactly APP_BASE_URL/auth/callback; the client secret is wrong; the provider has no signing key (HS256 tokens are refused); a clock that is several minutes off; or the browser took too long and the one-time code ran out.
no_identity Authentik signed the person in but sent no sub. Check the provider's scopes include openid.
(not recorded) no_pending_login A page left open too long, a bookmarked callback address, or the session cookie was not kept. If it happens every time, the cookie is the problem — see the next row.

Other symptoms:

Symptom Likely cause
You sign in at Authentik and land on the login page again, over and over The session cookie is not being kept. In production it is Secure, so the site must be opened over HTTPS; behind a reverse proxy, check it sends X-Forwarded-Proto. Also check APP_BASE_URL is the address in the browser's address bar.
Everyone is signed out after a restart SESSION_SECRET changed (or is generated fresh each start), or the data/sessions folder is not on the persistent volume.
New people are all viewers although roles from groups is on The sign-in carried no groups: check the claim name, and that the Authentik user is in the groups. Look at the Users page — the groups seen at each person's last sign-in are shown there.
Roles from groups did nothing to an administrator Working as intended if they are the only administrator (a group rule never removes the last one); the audit log says role_from_groups_blocked.
"Cannot remove the only admin" Same safeguard, on the Users page. Make someone else an administrator first.
A person with a different login at Authentik (renamed, merged) shows up as a new person The app matches on sub, not on name or email. See the subject-mode warning above.

If you are locked out

There is no local password, so if the identity provider is down or misconfigured nobody can sign in. People who are already signed in keep working until their session ends. To get back in, fix the provider or the AUTHENTIK_* settings and restart the container.

If the only administrator's account was changed so that nobody is an administrator any more, promote someone directly in the database (stop the app, or accept that it is a single quick write; take a copy of the data folder first — see BACKUP.md):

sqlite3 data/homelab-manager.sqlite "UPDATE users SET role = 'admin' WHERE email = 'you@example.lan';"

Security notes

  • PKCE and state protect the code exchange; the callback is refused without the pending sign-in that the same browser started.
  • The ID token's signature is verified against Authentik's published keys, so the login does not depend on the connection to Authentik alone.
  • A new session id is issued at sign-in, so an id planted in the browser beforehand cannot be used.
  • Requests that change something are refused when they come from another origin (the cookie is SameSite=Lax, which does not stop another app on the same parent domain), including GET /auth/logout.
  • Sign-in is rate-limited to 20 attempts a minute per address, and each failure is audited.
  • Every response carries frame-ancestors 'none', X-Frame-Options: DENY, nosniff and a same-origin referrer policy.

Other identity providers

The code uses standard OIDC discovery (<issuer>/.well-known/openid-configuration), the authorization code flow with PKCE (S256), a confidential client, RS256-signed ID tokens with a published JWKS, and the sub, email, name/preferred_username, picture and a groups claim (name configurable) — nothing Authentik-specific. Keycloak, Authelia and similar providers should therefore work by putting their issuer URL, client id and secret in the AUTHENTIK_* variables and setting the groups claim name under Settings → Sign-in. This has not been tried; if you try one, make sure it signs with RS256 and that the redirect address is registered exactly.