- 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>
230 lines
17 KiB
Markdown
230 lines
17 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.
|
|
|
|
## 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) |
|
|
| `/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.
|