Files
notes/docs/home-server/authentication.md
T

175 lines
8.3 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-16"
sources:
- 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, all integrations below complete and Authelia retired.
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 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 |
| `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.
## 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_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:
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.