244 lines
12 KiB
Markdown
244 lines
12 KiB
Markdown
---
|
|
schema_version: 1
|
|
id: home-server.authentication
|
|
type: reference
|
|
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
|
|
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
|
|
reference: "Six-directory Backrest plan including Authentik and Wardrowbe; deployed Authentik container names confirmed, 2026-10-16"
|
|
- kind: owner-report
|
|
reference: "All stack environment values/secrets managed in Portainer; GitHub access uses PAT, 2026-10-06"
|
|
- kind: owner-report
|
|
reference: "Independent credential recovery unchanged: only restic key has independent custody, 2026-10-16"
|
|
- kind: repository
|
|
repository: jupiter-stacks
|
|
revision: d09df456ad331b8beb9a40615114ea8aae2dced5
|
|
paths:
|
|
- stacks/authentik/docker-compose.yml
|
|
- stacks/authentik/blueprints/jupiter.yaml
|
|
- stacks/authentik/.env.example
|
|
- stacks/beszel/docker-compose.yml
|
|
- stacks/dozzle/docker-compose.yml
|
|
- stacks/gitea/docker-compose.yml
|
|
- stacks/immich/docker-compose.yml
|
|
- stacks/paperless-ngx/docker-compose.yml
|
|
- stacks/portainer/portainer_start.sh
|
|
- stacks/wardrowbe/docker-compose.yml
|
|
- stacks/backrest/docker-compose.yml
|
|
- stacks/notes/docker-compose.yml
|
|
- stacks/prowlarr/docker-compose.yml
|
|
- stacks/radarr/docker-compose.yml
|
|
- stacks/sonarr/docker-compose.yml
|
|
related: [home-server.reference, home-server.networking, home-server.portainer, home-server.backups, home-server.deployment]
|
|
update_triggers: [access-policy-change, authentication-change, secret-rotation, middleware-change]
|
|
unknowns:
|
|
- deployed-group-memberships
|
|
- per-application-local-login-and-account-linking-settings
|
|
- retired-authelia-data-retention
|
|
---
|
|
|
|
# Authentication
|
|
|
|
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 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 |
|
|
| --- | --- |
|
|
| Portal | `https://auth.umbra.mom` |
|
|
| Identity service | Authentik server + worker; image `2026.8.4` |
|
|
| Database | PostgreSQL 16; database/user `authentik` |
|
|
| Configuration | `stacks/authentik/blueprints/jupiter.yaml`; worker-mounted custom blueprint |
|
|
| Application MFA | `jupiter-app-authorization`; TOTP or WebAuthn; prompts for setup if none configured |
|
|
| Recent MFA | Five-minute reuse threshold avoids an immediate duplicate challenge |
|
|
| Host setup access | Loopback `127.0.0.1:9000` -> server `9000` |
|
|
|
|
## Access groups
|
|
|
|
Owner terminology maps to the blueprint's exact group names:
|
|
|
|
| Intended group | Authentik group | Purpose / applications |
|
|
| --- | --- | --- |
|
|
| Admin | `admins` | Owner only; server health/operations: Backrest, Beszel, Dozzle, Notes, Prowlarr, Radarr, Sonarr |
|
|
| Developers | `development` | Development services: Gitea, Portainer |
|
|
| Clients | `clients` | Useful end-user services: Immich, Paperless, Wardrowbe |
|
|
|
|
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.
|
|
Membership in `admins` alone does not grant the development/client applications;
|
|
users needing multiple categories need the corresponding memberships.
|
|
Actual deployed membership assignments were not supplied.
|
|
|
|
## Native OIDC
|
|
|
|
Each client uses a confidential authorization-code provider, strict redirect URIs,
|
|
per-provider issuer and the shared application-MFA authorization flow.
|
|
Issuer pattern: `https://auth.umbra.mom/application/o/<client-id>/`.
|
|
|
|
| Client ID | Application hostname | Integration configuration |
|
|
| --- | --- | --- |
|
|
| `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; 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 |
|
|
| `wardrowbe` | `wardrobe.umbra.mom` | Compose OIDC settings for frontend and backend/workers |
|
|
|
|
Dozzle's custom profile mapping emits `dozzle_roles: ["none"]` for `admins`
|
|
members and `[]` otherwise; application access is separately restricted to
|
|
`admins`. The email mapping asserts `email_verified` only when the user has
|
|
an email and their `email_verified` attribute is explicitly true.
|
|
|
|
OIDC integration does not prove local password login is disabled or application
|
|
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=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) |
|
|
| 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 credentials, permissions, boards, settings and API keys. Password
|
|
credentials are retained but cannot be used while only OIDC is enabled.
|
|
|
|
To complete linking:
|
|
|
|
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
|
|
`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. 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. 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
|
|
|
|
Backrest (`backups.umbra.mom`), Notes, Prowlarr, Radarr and Sonarr retain
|
|
proxy-based protection. Their routers attach `authentik@docker`:
|
|
|
|
```text
|
|
Traefik -> http://authentik-server:9000/outpost.goauthentik.io/auth/traefik
|
|
```
|
|
|
|
The embedded outpost serves five `forward_single` providers, each with an
|
|
explicit external host and empty `skip_path_regex`. A priority-1000 router
|
|
on those hosts sends `/outpost.goauthentik.io/` directly to Authentik,
|
|
bypassing forward-auth so callbacks can complete.
|
|
|
|
`trustForwardHeader=true`; forwarded response headers:
|
|
|
|
```text
|
|
X-authentik-username, X-authentik-groups, X-authentik-entitlements,
|
|
X-authentik-email, X-authentik-name, X-authentik-uid, X-authentik-jwt,
|
|
X-authentik-meta-jwks, X-authentik-meta-outpost, X-authentik-meta-provider,
|
|
X-authentik-meta-app, X-authentik-meta-version
|
|
```
|
|
|
|
Forward-auth applies only to attached routers. Authentik is not a global gate
|
|
for every service, directly published port, SSH connection or API token.
|
|
|
|
## State / secrets
|
|
|
|
| Host path | Container use |
|
|
| --- | --- |
|
|
| `/data/authentik/postgres` | PostgreSQL `/var/lib/postgresql/data`; identity, policy and MFA state |
|
|
| `/data/authentik/data` | Server + worker `/data`; persistent files |
|
|
| `/data/authentik/blueprints` | Worker `/blueprints/custom:ro`; host copy of repository blueprint |
|
|
|
|
Stack variable overrides/secrets are managed in Portainer; Compose retains
|
|
non-secret configuration. Required Authentik stack secrets:
|
|
|
|
```text
|
|
AUTHENTIK_SECRET_KEY
|
|
AUTHENTIK_DB_PASSWORD
|
|
OIDC_BESZEL_SECRET
|
|
OIDC_DOZZLE_SECRET
|
|
OIDC_GITEA_SECRET
|
|
OIDC_HOMARR_SECRET
|
|
OIDC_IMMICH_SECRET
|
|
OIDC_PAPERLESS_SECRET
|
|
OIDC_PORTAINER_SECRET
|
|
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:
|
|
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.
|
|
|
|
Public Traefik routing defaults off (`AUTHENTIK_PUBLIC_ROUTING=false`) for
|
|
private initial setup; enable only after securing the administrator account.
|
|
The owner reports public deployment complete; this default is not deployed state.
|
|
See [deployment](deployment.md) for the configuration surfaces and order.
|
|
|
|
`/data/authentik` and [Portainer state](portainer.md) are included in
|
|
[Backrest](backups.md). Backups stop Authentik server/worker and PostgreSQL;
|
|
new OIDC logins and forward-auth access are unavailable during that stop.
|
|
Recovery remains untested, with no independent admin/MFA or stack-secret
|
|
recovery arrangement; only the restic key has independent custody.
|
|
Retention/deletion of retired `/data/authelia` data is unconfirmed.
|
|
GitHub repository access uses a PAT; host SSH keys and tunnel credential files
|
|
are separate from stack environment variables.
|