Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)

Detailed engineering and feature implementation specifications.

implementation-specs/specs/BackendDatabaseConsolidation/TASK1.1.md 2,305 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

TASK 1.1: Define Keycloak integration and identity contract

Define the authentication and authorization contract that will replace Laravel's current database-backed user model.

This task establishes how Front, backend, and Keycloak interact before any persistence or controller refactors are implemented.

This task is primarily a design and implementation-alignment task.

Expected documentation and configuration touch points may include:

Define and document:

Keycloak realm/client ownership for this app,
whether Front uses OIDC authorization-code flow with server-side callback handling,
the token or session artifact Laravel should retain after login,
required user claims or lookup keys available to backend,
role model for portal access such as admin versus user,
logout flow across Front and Keycloak,
whether tenant membership is carried in token claims or resolved by backend membership lookup.

Recommended contract for this slice:

Keycloak owns login and user identity,
Laravel uses a non-DB session to retain authenticated user context,
backend validates Keycloak-issued bearer tokens or a backend-issued session-compatible token derived from Keycloak identity,
backend resolves tenant scope from identity, not from an arbitrary request header,
backend user-management operations integrate with Keycloak Admin APIs rather than local user tables.

[ ] A single chosen auth flow is documented for Front, backend, and Keycloak
[ ] Required claims, roles, or subject identifiers are defined
[ ] Tenant resolution source is defined
[ ] Admin user-management ownership is defined
[ ] The design does not require Laravel database access
[ ] The design removes Laravel Auth::attempt and Eloquent user-provider assumptions

Prefer one clear path over supporting multiple auth modes.
Avoid designing around the legacy Laravel users table because it is going away.
If tenant membership is likely to evolve, prefer backend-owned membership lookup keyed by Keycloak subject.