Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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:
|
||||
|
||||
Reference in new issue
Block a user