# TASK 1.1: Define Keycloak integration and identity contract

## Summary

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.

## Dependencies

- none

## Files to Modify

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

Expected documentation and configuration touch points may include:

- `specs/BackendDatabaseConsolidation/TASK.md`
- backend auth configuration files to be created later
- Front auth/session configuration files to be updated later

## Required Behavior

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.

## Acceptance Criteria

- [ ] 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

## Notes

- 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.