Files
notes/docs/home-server/authentication.md
T
2026-10-29 15:28:47 +00:00

136 lines
8.2 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: live-inspection
reference: "PostgreSQL moved to /home/jay/data/authentik/postgres on SSD 2026-10-27; server/worker restored with unchanged image and credentials"
- 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 16 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.
## Native SAML: Joplin
- Repository configuration: `https://notes.umbra.mom`, Authentik application
`joplin`, shared MFA authorization flow and per-user admission.
- Signed assertions and responses; required attributes `email` and `displayName`.
- ACS: `https://notes.umbra.mom/api/saml`; entity ID/audience:
`https://notes.umbra.mom`.
- Joplin reads `/data/joplin/saml/{sp.xml,idp.xml}` through a read-only bind.
Copy the SP file from `stacks/joplin/saml/sp.xml`; download IdP metadata from
`https://auth.umbra.mom/application/saml/joplin/metadata/` after applying the
blueprint. Refresh the metadata after signing-certificate rotation.
- Clients use **Joplin Server (SAML)**, not the password-based sync target.
No forward-auth on the API. Local password login is disabled by default.
- First SAML login creates a non-admin Joplin account. Existing password accounts
with the same email are not automatically linked; preserve their data and
plan migration before switching.
- Temporary `JOPLIN_LOCAL_AUTH_ENABLED=true` permits recovery-admin login but
bypasses Authentik; remove it and redeploy after administration.
- Session cleanup is disabled to avoid repeated interactive sync logins.
Removing an Authentik binding alone does not revoke Joplin sessions; disable
the Joplin user and revoke their sessions too.
## 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 |
| --- | --- |
| `/home/jay/data/authentik/postgres` | PostgreSQL `/var/lib/postgresql/data`; SSD since 2026-10-27 |
| `/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).