[main]: Add OIDC to homarr
This commit is contained in:
2 files changed
+74
-7
No files matched your search
@@ -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/<client-id>/`.
|
||||
| `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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user