Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -1,6 +1,6 @@
# Admin-Panel SSO via Authentik
Phase 09 Task #82. Status: **code-complete, awaits Authentik deploy**.
Phase 09 Task #82. Status: **operational**.
This document covers operating the admin-panel SSO flow once Phase 09 #81
has shipped the Authentik instance.
@@ -16,7 +16,7 @@ sequenceDiagram
Browser->>Web: GET /auth/admin/login
Web->>Web: createAdminSsoChallenge() (PKCE+state+nonce)
Web-->>Browser: 302 -> Authentik authorize, Set-Cookie: hivegrid_admin_sso_challenge
Web-->>Browser: 302 -> Authentik authorize, Set-Cookie: __Host-hivegrid_admin_sso_challenge
Browser->>Authentik: GET /application/o/authorize/...
Authentik-->>Browser: Login + MFA, then 302 /auth/admin/callback?code=...&state=...
Browser->>Web: GET /auth/admin/callback (with cookie)
@@ -36,29 +36,73 @@ sequenceDiagram
Authentik-->>Browser: 302 post_logout_redirect_uri -> /login?logged_out=1
```
## Admin cookie scope
Production and every HTTPS deployment use host-only
`__Host-hivegrid_admin_sso_challenge` and
`__Host-hivegrid_admin_sso_id_token` cookies. Both are `Secure`, `HttpOnly`,
`SameSite=Lax`, `Path=/`, and never carry a `Domain` attribute. `Path=/` is
required by the browser-enforced `__Host-` contract; because the admin UI has
its own hostname, that dedicated host is the narrowest safe compatible scope.
The application does not accept the former unprefixed names on HTTPS, so a
parent-domain or sibling-host cookie cannot shadow an admin SSO cookie.
Local HTTP development uses the distinct unprefixed names
`hivegrid_admin_sso_challenge` and `hivegrid_admin_sso_id_token`, without
`Secure`. They are compatibility fallbacks only and are never read by an
HTTPS deployment.
## Required environment
See `.env.example` for the canonical commented block. Coolify deployment:
| Key | Source |
| ---------------------------------------------- | ------------------------------------------------- |
| `AUTHENTIK_ISSUER_URL` | `https://auth.<base-domain>/application/o/hivegrid-admin-panel/` |
| `AUTHENTIK_ADMIN_CLIENT_ID` | Blueprint client_id (default `hivegrid-admin-panel`) |
| `AUTHENTIK_ADMIN_CLIENT_SECRET` | Authentik admin UI (Coolify vault) |
| `AUTHENTIK_ADMIN_REDIRECT_URI` | `https://admin.<base-domain>/auth/admin/callback` |
| `AUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI` | `https://admin.<base-domain>/login?logged_out=1` |
| `ADMIN_FALLBACK_LOGIN_ENABLED` | `false` (default), flip to `true` during recovery |
| `ADMIN_FALLBACK_LOGIN_EMAILS` | Comma-separated bootstrap emails |
| Key | Source |
| ------------------------------------------ | ---------------------------------------------------------------- |
| `AUTHENTIK_ISSUER_URL` | `https://auth.<base-domain>/application/o/hivegrid-admin-panel/` |
| `AUTHENTIK_ADMIN_CLIENT_ID` | Blueprint client_id (default `hivegrid-admin-panel`) |
| `AUTHENTIK_ADMIN_CLIENT_SECRET` | Authentik admin UI (Coolify vault) |
| `AUTHENTIK_ADMIN_JIT_DATABASE_URL` | PgBouncer URL for the dedicated `hivegrid_authentik_jit` login |
| `AUTHENTIK_ADMIN_REDIRECT_URI` | `https://admin.<base-domain>/auth/admin/callback` |
| `AUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI` | `https://admin.<base-domain>/login?logged_out=1` |
| `ADMIN_FALLBACK_LOGIN_ENABLED` | `false` (default), flip to `true` during recovery |
| `ADMIN_FALLBACK_LOGIN_EMAILS` | Comma-separated bootstrap emails |
The regular web `DATABASE_URL` remains authenticated as `hivegrid_app` and
cannot execute the Admin-JIT function. Only the verified
`/auth/admin/callback` path opens the separate
`AUTHENTIK_ADMIN_JIT_DATABASE_URL`; its `hivegrid_authentik_jit` role owns no
table or sequence privileges and receives `EXECUTE` only for
`hivegrid_provision_authentik_admin(...)`. PostgreSQL also checks
`session_user`, so switching roles or forwarding freely constructed claims
through the application connection fails closed.
Before deploying the RLS cutover into an existing environment, provision the
new login externally with the other managed roles. The non-superuser migrator
never creates or alters roles:
```sh
HIVEGRID_RLS_PROVISION_DATABASE_URL=<SUPERUSER_DATABASE_URL> \
HIVEGRID_RLS_MIGRATOR_PASSWORD=<MIGRATOR_PASSWORD> \
HIVEGRID_RLS_APP_PASSWORD=<APP_PASSWORD> \
HIVEGRID_RLS_WORKER_PASSWORD=<WORKER_PASSWORD> \
HIVEGRID_RLS_AUTHENTIK_JIT_PASSWORD=<AUTHENTIK_JIT_PASSWORD> \
pnpm run db:roles:provision
```
Then add the matching, PgBouncer-fronted
`AUTHENTIK_ADMIN_JIT_DATABASE_URL` only to the web resource. Run role
provisioning before `prisma migrate deploy`; the migration deliberately stops
with a prerequisite error when any managed role is absent or unsafe.
## Authentik group → role mapping
The OIDC `groups` claim drives the AdminUser role. Highest priority wins.
| Authentik group | Internal AdminUser role | Notes |
| ---------------- | ----------------------- | -------------------------------------- |
| Authentik group | Internal AdminUser role | Notes |
| ---------------- | ----------------------- | -------------------------------------------------------------------------------------------- |
| `hivegrid-admin` | `super_admin` | Full admin permissions; if user is in both `hivegrid-admin` and `hivegrid-staff`, this wins. |
| `hivegrid-staff` | `staff` | Limited admin permissions. |
| _other_ | _login rejected (403)_ | `admin.login.sso.failure` audit event with `reason=forbidden-group`. |
| `hivegrid-staff` | `staff` | Limited admin permissions. |
| _other_ | _login rejected (403)_ | `admin.login.sso.failure` audit event with `reason=forbidden-group`. |
Granular permission checks remain in `apps/web/app/utils/permissions/`;
the role is the coarse switch.
@@ -67,7 +111,7 @@ the role is the coarse switch.
1. Create the user in Authentik (manual or via SCIM/LDAP if integrated).
2. Add the user to the `hivegrid-admin` or `hivegrid-staff` group.
3. Enforce MFA enrollment in Authentik (provider-side).
3. The provider-specific authentication flow enrolls or validates TOTP.
4. User clicks "Sign in with SSO" on `https://admin.<domain>/login`.
5. First login triggers JIT-provisioning — AdminUser row appears in DB
with `ssoProvider='authentik'`, `ssoSubjectId=<sub>`, `ssoGroups=[...]`,
@@ -123,13 +167,7 @@ production rollout.
step-up challenge for the closed taxonomy:
```ts
const SENSITIVE_ADMIN_ACTIONS = [
"impersonation.start",
"tenant.delete",
"permission.grant",
"audit.export",
"data.export",
] as const;
const SENSITIVE_ADMIN_ACTIONS = ["impersonation.start", "tenant.delete", "permission.grant", "audit.export", "data.export"] as const;
```
The cache window matches the existing step-up state (10 minutes — see
@@ -141,15 +179,15 @@ implementation here.
## Audit-event reference
| Action key | Severity | Emitted by |
| ---------------------------------------- | -------- | ---------------------------------------------- |
| `admin.login.sso.success` | info | `/auth/admin/callback` after JIT success |
| `admin.login.sso.failure` | warn | Any `/auth/admin/*` early-return path |
| `admin.login.fallback.success` | warn | `/login` action (admin host, fallback path) |
| `admin.login.fallback.failure` | warn | `/login` action when gate rejects |
| `admin.logout.sso` | info | `/auth/admin/logout` |
| `admin.mfa.app.challenge.success` | info | `requireAdminMfaForAction` happy path |
| `admin.mfa.app.challenge.failure` | warn | `requireAdminMfaForAction` redirect/deny path |
| Action key | Severity | Emitted by |
| --------------------------------- | -------- | --------------------------------------------- |
| `admin.login.sso.success` | info | `/auth/admin/callback` after JIT success |
| `admin.login.sso.failure` | warn | Any `/auth/admin/*` early-return path |
| `admin.login.fallback.success` | warn | `/login` action (admin host, fallback path) |
| `admin.login.fallback.failure` | warn | `/login` action when gate rejects |
| `admin.logout.sso` | info | `/auth/admin/logout` |
| `admin.mfa.app.challenge.success` | info | `requireAdminMfaForAction` happy path |
| `admin.mfa.app.challenge.failure` | warn | `requireAdminMfaForAction` redirect/deny path |
All events carry `ip`, `userAgent`, `actorAdminUserId` (when resolvable)
and an action-specific `meta` JSON blob. The audit wrapper redacts any
@@ -158,18 +196,22 @@ persisting to `AuditEvent`.
## Troubleshooting
| Symptom | Cause / Fix |
| ------------------------------------------------------- | ------------------------------------------------------ |
| `/auth/admin/login` redirects to `/login?error=sso_unavailable` | env vars missing or Authentik unreachable. Check Sentry for `AdminSsoConfigError` (`discovery-failed`). |
| `error=sso_state_invalid` after Authentik | Challenge cookie expired, signed under stale secret, or tampered. Have user retry; check `CRYPTO_SECRET` rotation. |
| `error=sso_forbidden_group` | User not in `hivegrid-admin`/`hivegrid-staff`. Add them in Authentik then retry. |
| `error=sso_email_not_verified` | Authentik user has not verified their email; enforce verification in Authentik provider settings. |
| `error=sso_token_exchange_failed` | Client secret mismatch, clock-skew, or redirect-URI drift. Compare `.env` vs Authentik UI. |
| JWKS-stale after key rotation | openid-client refreshes JWKS lazily; first failure forces a refetch. If repeated, restart the web container. |
| Group claim empty in ID-token | Authentik provider must include `groups` scope mapping — see blueprint `03-application-hivegrid-admin.yaml`. |
| Symptom | Cause / Fix |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `/auth/admin/login` redirects to `/login?error=sso_unavailable` | env vars missing or Authentik unreachable. Check Sentry for `AdminSsoConfigError` (`discovery-failed`). |
| `error=sso_state_invalid` after Authentik | Challenge cookie expired, signed under stale secret, or tampered. Have user retry; check `CRYPTO_SECRET` rotation. |
| `error=sso_forbidden_group` | User not in `hivegrid-admin`/`hivegrid-staff`. Add them in Authentik then retry. |
| `error=sso_email_not_verified` | Authentik user has not verified their email; enforce verification in Authentik provider settings. |
| `error=sso_mfa_required` | The ID token has no `mfa` AMR. Assign the dedicated HiveGrid authentication flow to the provider, verify that its TOTP validation stage uses `configure` for users without a device, and keep the authorization request at `max_age=1` so a prior Authentik session cannot bypass validation. A first enrollment creates the device; the following fresh authentication proves possession. Do not enable the password fallback. |
| `error=sso_token_exchange_failed` | Client secret mismatch, clock-skew, or redirect-URI drift. Compare `.env` vs Authentik UI. |
| JWKS-stale after key rotation | openid-client refreshes JWKS lazily; first failure forces a refetch. If repeated, restart the web container. |
| Group claim empty in ID-token | Authentik provider must include `groups` scope mapping — see blueprint `03-application-hivegrid-admin.yaml`. |
## Rollback / kill-switch
- **MFA-flow rollback**: restore the provider's previous `authentication_flow`
from the pre-change Authentik snapshot. Keep the application-side MFA claim
check fail-closed; do not use fallback login as a substitute for MFA.
- **Disable SSO entry-point only**: unset the Authentik env vars and
enable the fallback. `/auth/admin/login` will redirect with
`?error=sso_unavailable`; the UI shows only the password form.
@@ -219,10 +219,9 @@ aws s3 cp --endpoint-url "$AUTHENTIK_S3_BACKUP_ENDPOINT" \
"s3://$AUTHENTIK_S3_BACKUP_BUCKET/authentik/$(date -u +%Y-%m-%d)/" \
./restore/ --recursive
# 2. Decrypt (symmetric fallback — use the same AUTHENTIK_SECRET_KEY)
# 2. Decrypt with the private key for AUTHENTIK_BACKUP_GPG_RECIPIENT
for f in ./restore/*.gpg; do
gpg --batch --yes --decrypt --passphrase "$AUTHENTIK_SECRET_KEY" \
--output "${f%.gpg}" "$f"
gpg --batch --yes --decrypt --output "${f%.gpg}" "$f"
done
# 3. Spin up a throwaway Postgres + restore
@@ -8,7 +8,7 @@ Use this order before reaching for any destructive command:
1. **Migration applied but app fails at boot** — Most likely cause: code does not yet handle a new column, OR new column lacks a backfill. Prefer **forward-fix**: deploy a hotfix patch that handles the schema, then continue.
2. **Migration breaks data integrity** — Restore from the most recent verified backup. Do not run `prisma migrate resolve --rolled-back` against production data without a backup snapshot.
3. **Seed produced wrong rows** — Idempotent seeds (the boilerplate's permissions/entitlements seeds are idempotent by design) tolerate re-runs after manual cleanup. Non-idempotent seed sections should never run in production.
3. **Lokaler/historischer Seed erzeugte falsche Zeilen** — Nur in einer wegwerfbaren lokalen Datenbank bereinigen und erneut prüfen. Allgemeines Seeding oder ein Re-Run gegen Staging/Produktion ist unter erzwungener RLS verboten.
## Reverting a migration locally
@@ -59,6 +59,8 @@ If step 3 fails halfway through, `prisma migrate resolve --rolled-back <migratio
## Undoing a seed run
> **Staging/Produktion:** Allgemeines Seeding ist unter erzwungener RLS nicht freigegeben. Die folgenden historischen Bereinigungshinweise sind keine Erlaubnis, den Produktions-Seed oder `permissions:sync` gegen eine produktionsnahe Datenbank auszuführen.
The boilerplate's production seed (`packages/db/dist/production-seed.server.js`) is gated on `NODE_ENV=production` and explicit `SEED_ADMIN_EMAIL` / `SEED_ADMIN_PASSWORD`. It is idempotent for the canonical permission/entitlement rows but may insert demo data when `SEED_DEMO_DATA=true` accidentally leaks into a non-local environment.
Undo procedure:
@@ -72,7 +74,7 @@ psql "$DATABASE_URL" -c "SELECT id, name FROM \"Tenant\" WHERE slug IN ('acme-co
# 3. Delete in dependency order (children first). NEVER use DELETE without a WHERE clause on a production database.
```
After cleanup, re-run the canonical (non-demo) seed to confirm idempotency:
Nur gegen eine wegwerfbare lokale Datenbank darf anschließend der kanonische (nicht Demo-)Seed zur Idempotenzprüfung erneut laufen:
```sh
SEED_DEMO_DATA=false NODE_ENV=production node packages/db/dist/production-seed.server.js
@@ -80,13 +82,13 @@ SEED_DEMO_DATA=false NODE_ENV=production node packages/db/dist/production-seed.s
## Permission/role sync rollback
`pnpm run permissions:sync` is idempotent. To undo an unwanted permission rename:
Der produktive Deploy verwendet nicht `pnpm run permissions:sync`, sondern den fail-closed globalen Reconcile in `start.sh migrate`. Schlägt er fehl, werden seine Katalogänderungen und temporären DML-Grants an `hivegrid_rls_definer` gemeinsam zurückgerollt; `FORCE ROW LEVEL SECURITY` bleibt aktiv. Bereits zuvor erfolgreich angewandte Prisma-Migrationen bleiben bestehen.
1. Revert the offending commit in `packages/db/src/permissions-seed.server.ts`.
2. Re-run `pnpm run permissions:sync` against staging.
3. Run `verify:permission-matrix` to assert documentation parity.
1. Rollout gestoppt lassen und den redigierten Fehlernachweis sichern; weder allgemeinen Seed noch `permissions:sync` starten.
2. Katalogdefinition oder Reconcile-Code per geprüftem Forward-Fix korrigieren und den vollständigen One-shot-Pfad erneut ausführen.
3. Hat ein fehlerhafter Reconcile bereits committed, vor jeder Datenkorrektur Backup/Restore-Punkt bestätigen und die Korrektur als explizit freigegebene, auditierte Operator-Aktion ausführen.
Permission rows themselves are immutable identifiers; the seed only adds/updates. Manual `DELETE FROM "Permission" WHERE name = '…'` is risky because foreign-key references in `RolePermission` will cascade.
Tenant-eigene Rollen und Rollen mit `isTemplateOrigin = true` dürfen auch beim Rollback nicht automatisiert verändert oder nachgezogen werden. Manuelles `DELETE FROM "Permission" WHERE name = '…'` bleibt wegen kaskadierender `RolePermission`-Referenzen unzulässig.
## Practice drill
@@ -195,7 +195,6 @@ After docs-only changes:
```sh
pnpm run verify:docs-links
pnpm run verify:production-docs
```
After runtime changes: