Files
notes/docs/home-server/authentication.md
T
2026-10-29 15:28:47 +00:00

8.2 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
per-user-access
secrets
private-infrastructure 2026-10-27
kind reference
live-inspection PostgreSQL moved to /home/jay/data/authentik/postgres on SSD 2026-10-27; server/worker restored with unchanged image and credentials
kind reference
owner-report 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 revision paths
repository jupiter-stacks 12fb1b96e01fc062fdce4c216f11eb5d7ce716ed
stacks/authentik/docker-compose.yml
stacks/authentik/blueprints/jupiter.yaml
stacks/authentik/.env.example
stacks/homarr/docker-compose.yml
home-server.networking
home-server.deployment
home-server.backups
home-server.portainer
access-policy-change
authentication-change
secret-rotation
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.

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

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.