Files
Homelab-manager/docs/SSO.md
T
bobbanandClaude Sonnet 5.5 655b1443ec Move Authentik users and groups to their own tab
Apps → Authentik now has two tabs for administrators: Status (the outposts,
certificates, tokens and alerts, as before) and Users and groups (New user,
Users and Groups). The tab is a ?view=users link like the other pages' tabs;
everyone else sees only the status. Docs updated to name the tab.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-01 01:08:07 +01:00

231 lines
18 KiB
Markdown

# 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](https://goauthentik.io/)** and the settings are named after it; any provider that speaks standard OIDC *can* work
(see [Other identity providers](#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](#how-sign-in-works)
- [What you need before you start](#what-you-need-before-you-start)
- [1. Set up Authentik](#1-set-up-authentik)
- [2. Set up the app](#2-set-up-the-app)
- [3. The first sign-in](#3-the-first-sign-in)
- [Roles](#roles) — by hand, or from groups
- [Sessions and signing out](#sessions-and-signing-out)
- [What does *not* use SSO](#what-does-not-use-sso)
- [Troubleshooting](#troubleshooting)
- [If you are locked out](#if-you-are-locked-out)
- [Security notes](#security-notes)
## 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](#roles)), 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:
```bash
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`):
```ini
# 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](#roles)).
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. A person an administrator makes from **Apps → Authentik → Users and groups** is a new Authentik user, no more: to sign in here they still have to be allowed into the application (its group binding or policy), and they start as a viewer like anyone else.
## 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](../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](PROMETHEUS-GRAFANA.md) |
| `/api/v1/…` | scripts, Home Assistant | a *personal API token* (user menu → API tokens) — see [API.md](API.md) |
| `/api/heartbeat/<token>` | cron jobs | the heartbeat's own address — see [HEARTBEATS-AND-CALENDAR.md](HEARTBEATS-AND-CALENDAR.md) |
| `/api/public/…` | status pages, the wall display, the calendar feed | a *share link* (Settings → Share links) |
| `/api/alert-actions/<token>…` | the buttons and links on a notification | a signed token for the alerts in one message, valid 24 hours — see [WEBHOOKS.md](WEBHOOKS.md#buttons-on-notifications) |
| `/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](../BACKUP.md)):
```bash
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.