--- schema_version: 1 id: home-server.authentication type: reference scope: [jupiter, authentik, oidc, forward-auth, access-groups, secrets] sensitivity: private-infrastructure last_reviewed: "2026-10-18" sources: - kind: owner-report reference: "Requested Authentik-only Homarr login and read-only Docker socket proxy; deployment not confirmed, 2026-10-18" - kind: owner-report reference: "Homarr Authentik login created a separate account; requested linking to existing jay account, 2026-10-18" - kind: repository repository: jupiter-stacks revision: 026cfa58b601165342b278401183c5fed5a50db2 paths: - stacks/homarr/docker-compose.yml - stacks/homarr/.env.example - stacks/authentik/docker-compose.yml - stacks/authentik/blueprints/jupiter.yaml - stacks/authentik/.env.example - kind: owner-report reference: "Authentik fully deployed, all listed app integrations complete and Authelia retired; OIDC and three-group motivation, 2026-10-16" - kind: owner-report reference: "Six-directory Backrest plan including Authentik and Wardrowbe; deployed Authentik container names confirmed, 2026-10-16" - kind: owner-report reference: "All stack environment values/secrets managed in Portainer; GitHub access uses PAT, 2026-10-06" - kind: owner-report reference: "Independent credential recovery unchanged: only restic key has independent custody, 2026-10-16" - kind: repository repository: jupiter-stacks revision: d09df456ad331b8beb9a40615114ea8aae2dced5 paths: - stacks/authentik/docker-compose.yml - stacks/authentik/blueprints/jupiter.yaml - stacks/authentik/.env.example - stacks/beszel/docker-compose.yml - stacks/dozzle/docker-compose.yml - stacks/gitea/docker-compose.yml - stacks/immich/docker-compose.yml - stacks/paperless-ngx/docker-compose.yml - stacks/portainer/portainer_start.sh - stacks/wardrowbe/docker-compose.yml - stacks/backrest/docker-compose.yml - stacks/notes/docker-compose.yml - stacks/prowlarr/docker-compose.yml - stacks/radarr/docker-compose.yml - stacks/sonarr/docker-compose.yml related: [home-server.reference, home-server.networking, home-server.portainer, home-server.backups, home-server.deployment] update_triggers: [access-policy-change, authentication-change, secret-rotation, middleware-change] unknowns: - deployed-group-memberships - per-application-local-login-and-account-linking-settings - retired-authelia-data-retention --- # Authentication Authentik replaces Authelia. The owner wanted native OIDC rather than only forward-auth, with three access groups separating server administration, development tools and client-facing services. The owner reports the migration fully deployed as of 2026-10-16 and Authelia retired. Homarr OIDC login was reported working on 2026-10-18; linking to the existing account is configured in the repository but has not been confirmed successful. Configuration details below are repository evidence, not live inspection. | Component | Configuration | | --- | --- | | Portal | `https://auth.umbra.mom` | | Identity service | Authentik server + worker; image `2026.8.4` | | Database | PostgreSQL 16; database/user `authentik` | | Configuration | `stacks/authentik/blueprints/jupiter.yaml`; worker-mounted custom blueprint | | Application MFA | `jupiter-app-authorization`; TOTP or WebAuthn; prompts for setup if none configured | | Recent MFA | Five-minute reuse threshold avoids an immediate duplicate challenge | | Host setup access | Loopback `127.0.0.1:9000` -> server `9000` | ## Access groups Owner terminology maps to the blueprint's exact group names: | Intended group | Authentik group | Purpose / applications | | --- | --- | --- | | Admin | `admins` | Owner only; server health/operations: Backrest, Beszel, Dozzle, Notes, Prowlarr, Radarr, Sonarr | | Developers | `development` | Development services: Gitea, Portainer | | Clients | `clients` | Useful end-user services: Immich, Paperless, Wardrowbe | Each application in the access-group table has an enabled group binding; `policy_engine_mode: all`; binding failure result is false. All three groups have `is_superuser: false`: `admins` application access is not Authentik superuser status. No group hierarchy or membership assignment is declared by this blueprint. Membership in `admins` alone does not grant the development/client applications; users needing multiple categories need the corresponding memberships. Actual deployed membership assignments were not supplied. ## Native OIDC Each client uses a confidential authorization-code provider, strict redirect URIs, per-provider issuer and the shared application-MFA authorization flow. Issuer pattern: `https://auth.umbra.mom/application/o//`. | Client ID | Application hostname | Integration configuration | | --- | --- | --- | | `beszel` | `beszel.umbra.mom` | Database/UI provider; password-auth disable flag in Compose | | `dozzle` | `logs.umbra.mom` | Compose OIDC settings; no forward-auth middleware | | `gitea` | `gitea.umbra.mom` | Database/UI authentication source; Compose requires login for account linking and disables automatic registration | | `homarr` | `umbra.mom` | Compose OIDC settings; Authentik-only login configured; verified-email linking to existing password accounts enabled | | `immich` | `photos.umbra.mom` | Database/UI OAuth settings; web and mobile callbacks registered | | `paperless` | `paperless.umbra.mom` | Compose OpenID Connect/allauth configuration; PKCE enabled; signups disabled | | `portainer` | `portainer.umbra.mom`, `portainer.local.umbra.mom` | Database/UI OAuth settings; both callback hosts registered | | `wardrowbe` | `wardrobe.umbra.mom` | Compose OIDC settings for frontend and backend/workers | Dozzle's custom profile mapping emits `dozzle_roles: ["none"]` for `admins` members and `[]` otherwise; application access is separately restricted to `admins`. The email mapping asserts `email_verified` only when the user has an email and their `email_verified` attribute is explicitly true. OIDC integration does not prove local password login is disabled or application roles are synchronized. Beszel and Paperless retain migration-safe local-login defaults in Compose; deployed overrides and account-linking details were not supplied. Application permissions and existing sessions remain app-managed. ### Homarr Homarr uses native OIDC, not a Traefik forward-auth gate. Its Authentik provider is `jupiter-homarr`, with the shared application-MFA flow. | Setting | Value | | --- | --- | | Login providers | `AUTH_PROVIDERS=oidc` (Authentik only) | | Issuer | `https://auth.umbra.mom/application/o/homarr/` | | Client ID / display name | `homarr` / `Authentik` | | Callback | `https://umbra.mom/api/auth/callback/oidc` (strict match) | | Requested scopes | `openid email profile` | | Client secret | `OIDC_HOMARR_SECRET` in both the Homarr and Authentik stack environments | | Existing-account linking | `AUTH_OIDC_ENABLE_DANGEROUS_CREDENTIALS_LINKING=true` | An OIDC login initially created a separate user instead of signing into the existing `jay` password account. Linking is now enabled in Compose; it matches email addresses, not usernames, and preserves the existing account's username, password credentials, permissions, boards, settings and API keys. Password credentials are retained but cannot be used while only OIDC is enabled. To complete linking: 1. Before deploying Authentik-only login, back up `/data/homarr/appdata`, then sign in with the local administrator account and ensure `jay`'s email exactly matches the intended Authentik user's. 2. Independently verify ownership of that email before setting the Authentik user's `email_verified` attribute to boolean `true`, not string `"true"`. The existing email scope mapping requires this before issuing `email_verified: true`; do not mark every user's email verified. 3. Preserve or transfer anything owned by the duplicate OIDC account, then delete only that duplicate through Homarr's user management. Do not delete `jay`. An existing OIDC link otherwise continues using the duplicate. 4. Confirm Authentik login links to `jay` with administrator access and the existing boards and permissions before disabling password login. If linking still needs setup, temporarily use `AUTH_PROVIDERS=credentials,oidc` and redeploy. Once working, pull/redeploy with `AUTH_PROVIDERS=oidc`. The linking setting applies to all matching password accounts, not just `jay`. Only trusted administrators should mark Authentik emails verified. Password login is disabled in the current Compose configuration; successful deployment and account linking have not been confirmed. For recovery if Authentik is unavailable, temporarily restore `AUTH_PROVIDERS=credentials,oidc` and redeploy Homarr. That recovery setting bypasses Authentik MFA and application-access policies for password logins. Keep `SECRET_ENCRYPTION_KEY` unchanged. Homarr also has a read-only Docker socket proxy on an internal `docker-api` network. Only the proxy mounts `/var/run/docker.sock`; its API port is not published or connected to Traefik. Homarr's `Jupiter` endpoint permits inventory and logs, while the proxy blocks writes (`POST=0`). Container lifecycle controls are disabled. Redeploy the whole stack to create the proxy alongside Homarr. ## Forward-auth Backrest (`backups.umbra.mom`), Notes, Prowlarr, Radarr and Sonarr retain proxy-based protection. Their routers attach `authentik@docker`: ```text Traefik -> http://authentik-server:9000/outpost.goauthentik.io/auth/traefik ``` The embedded outpost serves five `forward_single` providers, each with an explicit external host and empty `skip_path_regex`. A priority-1000 router on those hosts sends `/outpost.goauthentik.io/` directly to Authentik, bypassing forward-auth so callbacks can complete. `trustForwardHeader=true`; 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 ``` Forward-auth applies only to attached routers. Authentik is not a global gate for every service, directly published port, SSH connection or API token. ## State / secrets | Host path | Container use | | --- | --- | | `/data/authentik/postgres` | PostgreSQL `/var/lib/postgresql/data`; identity, policy and MFA state | | `/data/authentik/data` | Server + worker `/data`; persistent files | | `/data/authentik/blueprints` | Worker `/blueprints/custom:ro`; host copy of repository blueprint | Stack variable overrides/secrets are managed in Portainer; Compose retains non-secret configuration. Required Authentik stack secrets: ```text AUTHENTIK_SECRET_KEY AUTHENTIK_DB_PASSWORD OIDC_BESZEL_SECRET OIDC_DOZZLE_SECRET OIDC_GITEA_SECRET OIDC_HOMARR_SECRET OIDC_IMMICH_SECRET OIDC_PAPERLESS_SECRET OIDC_PORTAINER_SECRET OIDC_WARDROWBE_SECRET ``` Client secrets are independently generated plaintext credentials, not old Authelia password hashes. The worker passes them to blueprint `!Env` entries. Keep each provider secret matched to its application configuration: Homarr uses `OIDC_HOMARR_SECRET`, Dozzle uses `DOZZLE_OIDC_CLIENT_SECRET`, Paperless `PAPERLESS_OIDC_CLIENT_SECRET`, and Wardrowbe `WARDROWBE_OIDC_CLIENT_SECRET`. Other clients store provider configuration in their databases/UIs. Public Traefik routing defaults off (`AUTHENTIK_PUBLIC_ROUTING=false`) for private initial setup; enable only after securing the administrator account. The owner reports public deployment complete; this default is not deployed state. See [deployment](deployment.md) for the configuration surfaces and order. `/data/authentik` and [Portainer state](portainer.md) are included in [Backrest](backups.md). Backups stop Authentik server/worker and PostgreSQL; new OIDC logins and forward-auth access are unavailable during that stop. Recovery remains untested, with no independent admin/MFA or stack-secret recovery arrangement; only the restic key has independent custody. Retention/deletion of retired `/data/authelia` data is unconfirmed. GitHub repository access uses a PAT; host SSH keys and tunnel credential files are separate from stack environment variables.