[main]: Add OIDC to homarr

This commit is contained in:
John Gatward committed 2026-10-18 16:26:43 +01:00
1 parent 00ce362969
commit 96114167f2
2 files changed
+74 -7

No files matched your search

+59 -4
View File
@@ -4,8 +4,19 @@ id: home-server.authentication
type: reference type: reference
scope: [jupiter, authentik, oidc, forward-auth, access-groups, secrets] scope: [jupiter, authentik, oidc, forward-auth, access-groups, secrets]
sensitivity: private-infrastructure sensitivity: private-infrastructure
last_reviewed: "2026-10-16" last_reviewed: "2026-10-18"
sources: 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 - kind: owner-report
reference: "Authentik fully deployed, all listed app integrations complete and Authelia retired; OIDC and three-group motivation, 2026-10-16" reference: "Authentik fully deployed, all listed app integrations complete and Authelia retired; OIDC and three-group motivation, 2026-10-16"
- kind: owner-report - kind: owner-report
@@ -46,7 +57,9 @@ unknowns:
Authentik replaces Authelia. The owner wanted native OIDC rather than only Authentik replaces Authelia. The owner wanted native OIDC rather than only
forward-auth, with three access groups separating server administration, forward-auth, with three access groups separating server administration,
development tools and client-facing services. The owner reports the migration 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. Configuration details below are repository evidence, not live inspection.
| Component | Configuration | | Component | Configuration |
@@ -69,7 +82,7 @@ Owner terminology maps to the blueprint's exact group names:
| Developers | `development` | Development services: Gitea, Portainer | | Developers | `development` | Development services: Gitea, Portainer |
| Clients | `clients` | Useful end-user services: Immich, Paperless, Wardrowbe | | 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`: binding failure result is false. All three groups have `is_superuser: false`:
`admins` application access is not Authentik superuser status. `admins` application access is not Authentik superuser status.
No group hierarchy or membership assignment is declared by this blueprint. No group hierarchy or membership assignment is declared by this blueprint.
@@ -88,6 +101,7 @@ Issuer pattern: `https://auth.umbra.mom/application/o/<client-id>/`.
| `beszel` | `beszel.umbra.mom` | Database/UI provider; password-auth disable flag in Compose | | `beszel` | `beszel.umbra.mom` | Database/UI provider; password-auth disable flag in Compose |
| `dozzle` | `logs.umbra.mom` | Compose OIDC settings; no forward-auth middleware | | `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 | | `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 | | `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 | | `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 | | `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 defaults in Compose; deployed overrides and account-linking details were not
supplied. Application permissions and existing sessions remain app-managed. 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 ## Forward-auth
Backrest (`backups.umbra.mom`), Notes, Prowlarr, Radarr and Sonarr retain Backrest (`backups.umbra.mom`), Notes, Prowlarr, Radarr and Sonarr retain
@@ -146,6 +200,7 @@ AUTHENTIK_DB_PASSWORD
OIDC_BESZEL_SECRET OIDC_BESZEL_SECRET
OIDC_DOZZLE_SECRET OIDC_DOZZLE_SECRET
OIDC_GITEA_SECRET OIDC_GITEA_SECRET
OIDC_HOMARR_SECRET
OIDC_IMMICH_SECRET OIDC_IMMICH_SECRET
OIDC_PAPERLESS_SECRET OIDC_PAPERLESS_SECRET
OIDC_PORTAINER_SECRET OIDC_PORTAINER_SECRET
@@ -155,7 +210,7 @@ OIDC_WARDROWBE_SECRET
Client secrets are independently generated plaintext credentials, not old Client secrets are independently generated plaintext credentials, not old
Authelia password hashes. The worker passes them to blueprint `!Env` entries. Authelia password hashes. The worker passes them to blueprint `!Env` entries.
Keep each provider secret matched to its application configuration: 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`. `PAPERLESS_OIDC_CLIENT_SECRET`, and Wardrowbe `WARDROWBE_OIDC_CLIENT_SECRET`.
Other clients store provider configuration in their databases/UIs. Other clients store provider configuration in their databases/UIs.
+15 -3
View File
@@ -4,8 +4,16 @@ id: home-server.deployment
type: reference type: reference
scope: [jupiter, portainer, github, stack-deployment, secrets] scope: [jupiter, portainer, github, stack-deployment, secrets]
sensitivity: private-infrastructure sensitivity: private-infrastructure
last_reviewed: "2026-10-16" last_reviewed: "2026-10-18"
sources: 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 - kind: owner-report
reference: "Portainer GitHub/main/PAT configuration, environment management and manual pull/redeploy workflow, 2026-10-06" reference: "Portainer GitHub/main/PAT configuration, environment management and manual pull/redeploy workflow, 2026-10-06"
- kind: owner-report - kind: owner-report
@@ -70,11 +78,15 @@ requires more than pulling Compose:
| Surface | Required state | | 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 | | 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 | | Authentik database | Administrator, MFA enrolment, group memberships, applied providers/application policies |
| Application databases/UIs | Beszel, Gitea, Immich and Portainer OIDC setup/account linking | | 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 For initial setup, keep `AUTHENTIK_PUBLIC_ROUTING=false` and access the
loopback-published `127.0.0.1:9000` privately, for example through SSH forwarding. loopback-published `127.0.0.1:9000` privately, for example through SSH forwarding.