[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
|
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.
|
||||||
|
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
Reference in new issue
Block a user