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

8.3 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-16
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, all integrations below complete and Authelia retired. 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 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
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.

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_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: 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.