Files
notes/docs/home-server/authentication.md
T

11 KiB

schema_version, id, type, scope, sensitivity, last_reviewed, sources, related, update_triggers, unknowns
schema_version id type scope sensitivity last_reviewed sources related update_triggers unknowns
1 home-server.authentication reference
jupiter
authentik
oidc
forward-auth
access-groups
secrets
private-infrastructure 2026-10-18
kind reference
owner-report Homarr Authentik login created a separate account; requested linking to existing jay account, 2026-10-18
kind repository revision paths
repository jupiter-stacks 026cfa58b601165342b278401183c5fed5a50db2
stacks/homarr/docker-compose.yml
stacks/homarr/.env.example
stacks/authentik/docker-compose.yml
stacks/authentik/blueprints/jupiter.yaml
stacks/authentik/.env.example
kind reference
owner-report Authentik fully deployed, all listed app integrations complete and Authelia retired; OIDC and three-group motivation, 2026-10-16
kind reference
owner-report Six-directory Backrest plan including Authentik and Wardrowbe; deployed Authentik container names confirmed, 2026-10-16
kind reference
owner-report All stack environment values/secrets managed in Portainer; GitHub access uses PAT, 2026-10-06
kind reference
owner-report Independent credential recovery unchanged: only restic key has independent custody, 2026-10-16
kind repository revision paths
repository jupiter-stacks d09df456ad331b8beb9a40615114ea8aae2dced5
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
home-server.reference
home-server.networking
home-server.portainer
home-server.backups
home-server.deployment
access-policy-change
authentication-change
secret-rotation
middleware-change
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>/.

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; local password login retained; 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=credentials,oidc
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 login, permissions, boards, settings and API keys.

To complete linking:

  1. 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. Pull/redeploy Homarr in Portainer to apply the linking setting, sign out, then sign in using Authentik and confirm the session uses jay with the existing boards and permissions.

The linking setting applies to all matching password accounts, not just jay. Only trusted administrators should mark Authentik emails verified. Local password login remains available for recovery and bypasses Authentik MFA and application-access policies. Keep SECRET_ENCRYPTION_KEY unchanged.

Forward-auth

Backrest (backups.umbra.mom), Notes, Prowlarr, Radarr and Sonarr retain proxy-based protection. Their routers attach authentik@docker:

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:

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:

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 for the configuration surfaces and order.

/data/authentik and Portainer state are included in Backrest. 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.