Skip to content

feat(auth): generic OIDC issuer and runtime dashboard auth config (#388) - #404

Merged
telivity-otaip merged 7 commits into
TelivityAI:mainfrom
cawicher:oidc-generico
Nov 11, 2026
Merged

telivity-otaip merged 7 commits into
TelivityAI:mainfrom
cawicher:oidc-generico

Conversation

@cawicher

Copy link
Copy Markdown
Contributor

Closes #388.

What this does

HAIP can now run with any OIDC provider (Zitadel, Authentik, Authelia, Entra ID, …) instead of Keycloak, and the published image no longer needs a rebuild per environment: the dashboard reads its login settings from the API at runtime.

With OIDC_ISSUER unset nothing changes — issuer, JWKS path, claims and the azp allow-list behave exactly as today, and the dashboard keeps its build-time VITE_* settings.

API

  • oidc-config.ts: one resolver for both verifiers (JwtStrategy and WsAuthService), so HTTP and WebSocket keep agreeing on who may call.
    • Generic mode: OIDC_ISSUER, OIDC_JWKS_URI (required — providers disagree on the path), OIDC_AUDIENCE.
    • In generic mode * in KEYCLOAK_ALLOWED_AZP / OIDC_ALLOWED_AZP accepts any client; aud stays the boundary. Useful when every integration has its own service account. A literal * in Keycloak mode still names no client.
  • Claims: roles from realm_access.roles, Zitadel's urn:zitadel:iam:org:project:roles (or its per-project form), or a flat roles array; property scope from property_ids, or from role keys property:<uuid> (prefix configurable). Property roles are stripped from roles.
  • GET /api/v1/auth/config — @Public(), returns only what the browser needs to start a login (issuer, client id, scope) and never a secret.
  • users.keycloak_sub → text (migration 0032): non-Keycloak subjects are not UUIDs (Zitadel's are numeric), and the lookup of such a sub against a uuid column was a 500. The admin CreateUserDto and integration:link accept any OIDC subject (1–255 printable ASCII).
  • The production image now ships packages/database/dist/link-integration-principal.js, so service principals can be linked without pnpm/tsx (separate commit).

Dashboard

  • loadAuthConfig() runs before the first render; with an oidcIssuer it builds keycloak-js with GenericOidcConfig ({ clientId, oidcProvider }, supported by keycloak-js 26). keycloak / AUTH_ENABLED stay the same exports (live bindings), so AuthContext and socket.ts barely change.
  • Roles are read with the same mapping; email/name fall back to the ID token (some providers keep profile claims there).
  • Generic providers match redirect URIs exactly, so in generic mode the login returns to the app root.

Cron

  • OIDC_TOKEN_URL / OIDC_TOKEN_SCOPE in scripts/cron/_common.sh.

Docs

  • docs/integrations/oidc-generic.md (variables, claims, Zitadel in five steps), .env.example, service-principal and cron READMEs.

Tests

  • oidc-generic.spec.ts (19): config resolution in both modes, claim mapping (Zitadel, Keycloak unchanged, Entra-style), dashboard config without secrets, azp wildcard only in generic mode, and an end-to-end WsAuthService.verify against a local JWKS server (RS256, Zitadel-shaped token with numeric sub; wrong aud/iss/azp refused).
  • unauthenticated-routes.spec.ts: /auth/config stays public and secret-free.
  • integration-principal.spec.ts: subjects beyond UUIDs; empty / whitespace / over-long refused.
  • pnpm typecheck and pnpm lint clean (0 errors).
  • Full workspace suite with the CI environment (node scripts/sync-test-count.mjs, Postgres 16 + Redis 7): 2666 passing across 312 files, 0 failures; README and docs/test-stats.json synced (+21 tests, +1 file).

Verified end to end against Zitadel v4.20.2 (with Login V2): dashboard login through the Zitadel login UI, and service accounts with JWT access tokens calling the staff REST API, scoped by property:<uuid> roles (403 on other properties).

🤖 Generated with Claude Code

cawicher and others added 7 commits November 10, 2026 16:05
…livityAI#388)

The API validated only Keycloak-issued JWTs (issuer, JWKS path and claims
were fixed to the Keycloak layout) and the dashboard baked its Keycloak
settings in at build time, so the published image could not be used behind
a real domain or with another identity provider.

- OIDC_ISSUER switches the API to any OIDC provider (OIDC_JWKS_URI,
  OIDC_AUDIENCE); with it unset, Keycloak mode is unchanged. One resolver
  (oidc-config.ts) feeds both verifiers, so HTTP and WebSocket agree.
- Claims: roles from realm_access.roles, Zitadel project roles or a flat
  `roles` array; property scope from property_ids or `property:<uuid>`
  role keys. In generic mode `*` in the azp allow-list accepts any client
  (aud stays the boundary).
- GET /api/v1/auth/config (public, no secrets) hands the dashboard its
  login settings; the dashboard loads them before the first render and
  uses keycloak-js' GenericOidcConfig, falling back to VITE_* values.
- users.keycloak_sub becomes text (migration 0032): non-Keycloak subjects
  are not UUIDs (Zitadel's are numeric). The admin DTO and
  integration:link accept any OIDC subject.
- Cron scripts accept OIDC_TOKEN_URL / OIDC_TOKEN_SCOPE.
- Docs: docs/integrations/oidc-generic.md.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The production image runs only compiled dist/ (no tsx), so the
service-principal link step documented for integrations could not run in
it. Emit link-integration-principal like run-migrations and seed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The runtime config now carries the property-role prefix, and the
dashboard leaves property:<uuid> keys out of the user's roles, as the
API already does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Admin create previously allowed any non-empty string up to 255 chars
while integration:link enforced printable ASCII via isValidKeycloakSub.
Export OIDC_SUB_RE and @matches it on the DTO so both paths agree.

Co-authored-by: dusan <dusan@telivity.app>
Match API tokenRoleKeys: when the generic project-roles claim is absent,
fall back to urn:zitadel:iam:org:project:<aud>:roles so the UI shows the
same roles the API authorizes.

Co-authored-by: dusan <dusan@telivity.app>
+8 cases / +2 files from CreateUserDto and tokenRoles specs.

Co-authored-by: dusan <dusan@telivity.app>
@cursor

cursor Bot commented Nov 11, 2026

Copy link
Copy Markdown

Follow-up hygiene on this branch (additive; author history untouched):

  1. CreateUserDto.keycloakSub now @Matches(OIDC_SUB_RE) so create-user agrees with isValidKeycloakSub / integration:link (printable ASCII, 1–255). Spec added under create-user.dto.spec.ts.
  2. Dashboard tokenRoles falls back to per-audience Zitadel claim urn:zitadel:iam:org:project:<aud>:roles when the generic project-roles claim is absent (same order as API tokenRoleKeys). Covered in keycloak.spec.ts.
  3. Test counts synced. Tip: 38cb001.

Operator notes:

  • In generic mode, OIDC_ALLOWED_AZP / KEYCLOAK_ALLOWED_AZP=* makes aud the client boundary — keep OIDC_AUDIENCE tight.
  • GET /api/v1/auth/config is intentionally public (no secrets); serve the dashboard/API over TLS so runtime IdP steering can’t be MITM’d.
  • Docs already cover the generic-mode redirect-to-app-root tradeoff.

@TelivityAI TelivityAI deleted a comment from cursor Bot Nov 11, 2026
@TelivityAI TelivityAI deleted a comment from cursor Bot Nov 11, 2026
@telivity-otaip
telivity-otaip merged commit 83f88e5 into TelivityAI:main Nov 11, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature request: runtime auth configuration for the published API image (and generic OIDC support)

3 participants