--- 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 | 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).