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