Files
notes/docs/home-server/authentication.md
T
2026-10-27 12:21:10 +00:00

112 lines
6.7 KiB
Markdown

---
schema_version: 1
id: home-server.authentication
type: reference
scope: [jupiter, authentik, oidc, forward-auth, per-user-access, secrets]
sensitivity: private-infrastructure
last_reviewed: "2026-10-27"
sources:
- kind: owner-report
reference: "Authentik deployed/Authelia retired 2026-10-16; Homarr login 2026-10-18; per-user policy and account linking still unconfirmed 2026-10-26"
- kind: repository
repository: jupiter-stacks
revision: 12fb1b96e01fc062fdce4c216f11eb5d7ce716ed
paths: [stacks/authentik/docker-compose.yml, stacks/authentik/blueprints/jupiter.yaml, stacks/authentik/.env.example, stacks/homarr/docker-compose.yml]
related: [home-server.networking, home-server.deployment, home-server.backups, home-server.portainer]
update_triggers: [access-policy-change, authentication-change, secret-rotation]
unknowns: [deployed-per-user-bindings-and-jay-superuser-membership, per-application-local-login-and-account-linking, retired-authelia-data-retention]
---
# Authentication
- **Deployed:** Authentik replaces Authelia; portal `https://auth.umbra.mom`.
- **Repository intent, deployment unconfirmed:** direct per-user access and Homarr account linking.
- Backend: server + worker + PostgreSQL 16 (`authentik` DB/user).
- Blueprint: `stacks/authentik/blueprints/jupiter.yaml`; host copy must be applied separately.
- MFA: `jupiter-app-authorization`; TOTP/WebAuthn; setup if absent; five-minute reuse.
- Proxy transport/trust: [Networking](networking.md#listener-and-trust-boundaries).
## Per-user application access
- All 15 applications bind existing user `jay` at order `0`; `policy_engine_mode: any`.
- Add others under **Policy / Group / User Bindings**: enabled, non-negated **User** binding, order `10+`. Unassigned users are denied; manual higher-order bindings survive reapplication.
- Blueprint replaces custom `admins`, `development`, `clients` groups; does not create users or change passwords/MFA/app-native roles.
- **Keep Jay in the built-in superuser group** (`authentik Admins`); application admission is not administration.
- Before applying: back up Authentik, verify Jay's superuser membership, redeploy Trek's username-based admin mapping, copy/apply the host blueprint, assign retained users.
- Revoke existing application sessions/API keys separately when removing access.
## Native OIDC
- Confidential authorization-code clients; strict callbacks; shared MFA flow.
- Issuer: `https://auth.umbra.mom/application/o/<client-id>/`.
| Client ID | Host under `umbra.mom` | Configuration |
| --- | --- | --- |
| `beszel` | `beszel` | Database/UI provider; password-disable flag in Compose |
| `dozzle` | `logs` | Compose OIDC; `dozzle_roles: ["none"]`; read-only Docker proxy |
| `gitea` | `gitea` | Database/UI source; login required for linking; auto-registration disabled |
| `homarr` | Apex | Compose OIDC; verified-email linking |
| `immich` | `photos` | Database/UI OAuth; web + mobile callbacks |
| `paperless` | `paperless` | Compose allauth/OIDC; PKCE; signups disabled |
| `portainer` | `portainer`, `portainer.local` | Database/UI OAuth; both callback hosts |
| `trek` | `holidays` | Compose; `preferred_username == jay` grants app admin |
| `wardrowbe` | `wardrobe` | Compose frontend/backend/workers |
- Beszel/Paperless retain migration-safe local-login defaults; deployed overrides unconfirmed.
- OIDC does not synchronise native app roles or prove local login disabled.
- Email mapping emits `email_verified` only for an existing email with explicit boolean `true`.
### Homarr
| Setting | Value |
| --- | --- |
| Provider / login | `jupiter-homarr`; `AUTH_PROVIDERS=oidc` |
| Callback | `https://umbra.mom/api/auth/callback/oidc` |
| Scopes | `openid email profile` |
| Shared secret | `OIDC_HOMARR_SECRET` in Homarr + Authentik |
| Linking | `AUTH_OIDC_ENABLE_DANGEROUS_CREDENTIALS_LINKING=true` |
- Linking matches **email**, not username; applies to all matching password accounts.
- Preserve `SECRET_ENCRYPTION_KEY`; password credentials remain stored but unusable with OIDC-only login.
1. Back up `/data/homarr/appdata`; ensure existing `jay` email matches the intended identity.
2. Independently verify ownership, then set that user's `email_verified` to boolean `true`; never mark all users verified.
3. Preserve/transfer duplicate-account data, then delete **only the duplicate OIDC account**, not `jay`; an existing link otherwise wins.
4. Confirm login reaches `jay`, admin permissions and existing boards before disabling credentials. Temporarily use `AUTH_PROVIDERS=credentials,oidc` if needed.
- Credential fallback bypasses Authentik MFA/access policy for password logins.
- Internal `docker-api` proxy: only proxy mounts socket; no published API/Traefik attachment; inventory/logs allowed, `POST=0`, lifecycle controls disabled. Redeploy the whole stack.
## Forward-auth
- Protected apps: Backrest (`backups`), Notes, Prowlarr, Radarr, Sonarr, qBittorrent.
- Router middleware: `authentik@docker`; `trustForwardHeader=true`.
- Endpoint: `http://authentik-server:9000/outpost.goauthentik.io/auth/traefik`.
- Six embedded `forward_single` providers; explicit external hosts, empty `skip_path_regex`.
- Priority **1000** callback router: `/outpost.goauthentik.io/` goes directly to Authentik, bypassing forward-auth.
- qBittorrent keeps native login; internal Arr API traffic bypasses this browser gate.
- Only attached routers are protected; published ports, SSH and API tokens are separate boundaries.
Forwarded response headers:
```text
X-authentik-username, X-authentik-groups, X-authentik-entitlements,
X-authentik-email, X-authentik-name, X-authentik-uid, X-authentik-jwt,
X-authentik-meta-jwks, X-authentik-meta-outpost, X-authentik-meta-provider,
X-authentik-meta-app, X-authentik-meta-version
```
## State / secrets
| Host path | Container use |
| --- | --- |
| `/data/authentik/postgres` | PostgreSQL `/var/lib/postgresql/data` |
| `/data/authentik/data` | Server + worker `/data` |
| `/data/authentik/blueprints` | Worker `/blueprints/custom:ro` |
- `authentik-data`: internal DB/server/worker network; worker also uses `authentik-egress`, server uses `traefik`. Internal DB network does not imply full egress isolation.
- Secret inventory: `stacks/authentik/.env.example`; values in Portainer, consumed through `!Env`. Do not reuse Authelia hashes as client secrets.
- Match provider/application credentials: Homarr `OIDC_HOMARR_SECRET`; Dozzle `DOZZLE_OIDC_CLIENT_SECRET`; Paperless `PAPERLESS_OIDC_CLIENT_SECRET`; Wardrowbe `WARDROWBE_OIDC_CLIENT_SECRET`.
- Initial setup: `AUTHENTIK_PUBLIC_ROUTING=false`, SSH-forwarded `127.0.0.1:9000`; secure admin/MFA before public routing, prove OIDC before disabling local logins.
- Backup coverage, login downtime and credential recovery: [Backups](backups.md).