diff --git a/docs/home-server/authentication.md b/docs/home-server/authentication.md index be0f2aa..1574f19 100644 --- a/docs/home-server/authentication.md +++ b/docs/home-server/authentication.md @@ -6,6 +6,8 @@ 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 @@ -101,7 +103,7 @@ Issuer pattern: `https://auth.umbra.mom/application/o//`. | `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 | +| `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 | @@ -124,7 +126,7 @@ is `jupiter-homarr`, with the shared application-MFA flow. | Setting | Value | | --- | --- | -| Login providers | `AUTH_PROVIDERS=credentials,oidc` | +| 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) | @@ -135,12 +137,14 @@ is `jupiter-homarr`, with the shared application-MFA flow. 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. +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. 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. +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 @@ -148,14 +152,24 @@ To complete linking: 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. +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. Local -password login remains available for recovery and bypasses Authentik MFA and -application-access policies. Keep `SECRET_ENCRYPTION_KEY` unchanged. +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