From 96114167f2109a64096243cc9a9cdaf9c5c5d585 Mon Sep 17 00:00:00 2001 From: John Gatward Date: Sun, 18 Oct 2026 16:26:43 +0100 Subject: [PATCH] [main]: Add OIDC to homarr --- docs/home-server/authentication.md | 63 ++++++++++++++++++++++++++++-- docs/home-server/deployment.md | 18 +++++++-- 2 files changed, 74 insertions(+), 7 deletions(-) diff --git a/docs/home-server/authentication.md b/docs/home-server/authentication.md index 5e3b2e6..be0f2aa 100644 --- a/docs/home-server/authentication.md +++ b/docs/home-server/authentication.md @@ -4,8 +4,19 @@ id: home-server.authentication type: reference scope: [jupiter, authentik, oidc, forward-auth, access-groups, secrets] sensitivity: private-infrastructure -last_reviewed: "2026-10-16" +last_reviewed: "2026-10-18" sources: + - 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 @@ -46,7 +57,9 @@ unknowns: 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. +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 | @@ -69,7 +82,7 @@ Owner terminology maps to the blueprint's exact group names: | 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`; +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. @@ -88,6 +101,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 | | `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 | @@ -103,6 +117,46 @@ 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 @@ -146,6 +200,7 @@ AUTHENTIK_DB_PASSWORD OIDC_BESZEL_SECRET OIDC_DOZZLE_SECRET OIDC_GITEA_SECRET +OIDC_HOMARR_SECRET OIDC_IMMICH_SECRET OIDC_PAPERLESS_SECRET OIDC_PORTAINER_SECRET @@ -155,7 +210,7 @@ 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 +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. diff --git a/docs/home-server/deployment.md b/docs/home-server/deployment.md index 656a53b..6a650a4 100644 --- a/docs/home-server/deployment.md +++ b/docs/home-server/deployment.md @@ -4,8 +4,16 @@ id: home-server.deployment type: reference scope: [jupiter, portainer, github, stack-deployment, secrets] sensitivity: private-infrastructure -last_reviewed: "2026-10-16" +last_reviewed: "2026-10-18" sources: + - kind: repository + repository: jupiter-stacks + revision: 026cfa58b601165342b278401183c5fed5a50db2 + paths: + - stacks/homarr/docker-compose.yml + - stacks/authentik/docker-compose.yml + - stacks/authentik/blueprints/jupiter.yaml + - stacks/authentik/.env.example - kind: owner-report reference: "Portainer GitHub/main/PAT configuration, environment management and manual pull/redeploy workflow, 2026-10-06" - kind: owner-report @@ -70,11 +78,15 @@ requires more than pulling Compose: | Surface | Required state | | --- | --- | -| Portainer environment | Authentik persistent key, database password, seven provider client secrets; matching application secrets/overrides | +| Portainer environment | Authentik persistent key, database password, eight provider client secrets; matching application secrets/overrides | | Host files | Copy repository `stacks/authentik/blueprints/jupiter.yaml` into `/data/authentik/blueprints`; Git checkout alone does not populate this bind mount | | Authentik database | Administrator, MFA enrolment, group memberships, applied providers/application policies | | Application databases/UIs | Beszel, Gitea, Immich and Portainer OIDC setup/account linking | -| Application Compose | Dozzle, Paperless and Wardrowbe OIDC settings; five proxy-protected routers use `authentik@docker` | +| Application Compose | Dozzle, Homarr, Paperless and Wardrowbe OIDC settings; five proxy-protected routers use `authentik@docker` | + +Homarr uses the same `OIDC_HOMARR_SECRET` in both stack environments. Its +[account-linking steps](authentication.md#homarr) include verified email and +duplicate-account cleanup; redeploying Compose alone does not complete linking. For initial setup, keep `AUTHENTIK_PUBLIC_ROUTING=false` and access the loopback-published `127.0.0.1:9000` privately, for example through SSH forwarding.