Identity & Access (Keycloak)

Keycloak 26 is the platform's identity provider. Every API call into core is authenticated as an OAuth2 resource-server request against realm agentic-ai; tenancy itself is derived from the JWT's tenant_id claim. The subtle part is not OAuth — it is that core must accept tokens from two issuer URLs for the same realm, and that realm import files drift from the live realm.

flowchart TD
  U["User / client"] --> KC["Keycloak 26
realm: agentic-ai"]
  KC -->|"issues JWT
iss = public or internal URL"| APP["core (OAuth2 resource server)"]
  APP --> V{"issuer check"}
  V -->|"KEYCLOAK_ISSUER_URI
(raw/internal)"| OK["validate via JWKS"]
  V -->|"KEYCLOAK_ADDITIONAL_ISSUERS
auth.example.com/..."| OK
  V -->|"anything else"| R401["401"]
  OK --> AZP{"azp in allowed list?"}
  AZP -->|no| R401
  AZP -->|yes| CTX["TenantContext ← tenant_id claim
SecurityContext ← roles + PERM_*"]

1. Realm and clients

Realm agentic-ai (source: deploy/keycloak/agentic-ai-realm.json) registers these clients:

Identity-provider stubs for GitHub, Google and Microsoft exist in the realm JSON with placeholder client IDs (REPLACE_WITH_*) — they are enabled in the live realm only, one of the known JSON↔live drifts.

2. Roles and authorities

Beneath the roles sit granular PERM_* authorities enforced in SecurityConfig:

3. The dual-issuer requirement

Token validation additionally enforces an allowed-azp list: only tokens issued to the registered clients above are accepted. JWKS is fetched internally from http://keycloak:8080 (compose DNS or the in-cluster Service), not through the public domain: a CDN or WAF in front of auth.<your-domain> may block Python user agents and break the Python services' key fetch.

4. User management and signup

• Signup: /api/signup creates the Keycloak user and provisions the tenant schema in one flow.
• Admin operations: user management goes through the Keycloak Admin REST API via KEYCLOAK_ADMIN_BASE_URL (core/admin module's KeycloakAdminClient).
• unmanagedAttributePolicy=ADMIN_EDIT is mandatory. Without it, Keycloak drops non-mapped user attributes — including tenant_id — and every token for that user silently loses its tenant claim, which then breaks tenant resolution downstream.
• Post-import reconcile scripts exist because realm imports do not fully reproduce the live realm — run them after any realm re-import.

5. Security configuration

• SecurityConfig runs under profile !insecure — the insecure profile exists for local/test use and must never reach an environment.
• The app fails closed: with neither the secure nor the insecure profile, authentication is still enforced — there is no configuration mistake that silently opens the API.
• Route-level rules include /api/platform/** → ROLE_platform-admin; webhook paths are opened per-channel with their own signature validation instead of JWT auth.

6. Failure modes quick table