90 lines
2.7 KiB
Markdown
90 lines
2.7 KiB
Markdown
# Keycloak Architecture
|
|
|
|
This repository generates a fullstack CRUD application with **default Keycloak authentication and authorization**. Authentication is not an optional add-on and must not be described as a manual post-generation task.
|
|
|
|
---
|
|
|
|
# Default Auth Model
|
|
|
|
The generated application must use this runtime topology:
|
|
|
|
- **Frontend:** SPA served by Vite + React Admin
|
|
- **Backend:** NestJS API
|
|
- **Auth transport:** `Authorization: Bearer <access_token>`
|
|
- **Identity provider:** external Keycloak server
|
|
|
|
The generated application must **not** use:
|
|
|
|
- a BFF layer
|
|
- cookie/session authentication
|
|
- a custom in-app username/password login form
|
|
|
|
The generated application must use **redirect-based Keycloak login** only.
|
|
|
|
---
|
|
|
|
# Auth Is Part of Default Generation
|
|
|
|
The generator must produce:
|
|
|
|
- authenticated frontend bootstrap and request flow
|
|
- authenticated backend bootstrap and request guards
|
|
- auth-aware env examples
|
|
- auth-aware validation rules
|
|
- a root-level Keycloak realm import artifact that describes the Keycloak realm/client bootstrap
|
|
|
|
Repository defaults may use names such as `toir`, `toir-frontend`, `toir-backend`, and `toir-realm.json`, but future generations must parameterize realm name, client IDs, production URLs, and artifact filename from the generated project or explicit auth configuration.
|
|
|
|
The generated application must not require a separate prompt step such as "now add auth manually".
|
|
|
|
---
|
|
|
|
# Public and Protected Routes
|
|
|
|
The generated backend must keep:
|
|
|
|
- `GET /health` — public
|
|
|
|
All generated CRUD routes must be protected by default.
|
|
|
|
Authorization must be role-based and must use **only** Keycloak realm roles from `realm_access.roles`.
|
|
|
|
---
|
|
|
|
# Default Role Policy
|
|
|
|
Apply these RBAC defaults to generated CRUD controllers:
|
|
|
|
- `GET` list/detail: `viewer`, `editor`, `admin`
|
|
- `POST`, `PATCH`, `PUT`: `editor`, `admin`
|
|
- `DELETE`: `admin`
|
|
|
|
The frontend may use roles for display and permission awareness, but the backend remains the enforcement point.
|
|
|
|
---
|
|
|
|
# Token Contract
|
|
|
|
Generated auth context must guarantee that access tokens used by the SPA and API reliably contain:
|
|
|
|
- `sub`
|
|
- `aud`
|
|
- `realm_access.roles`
|
|
|
|
The frontend client and backend audience/client must be documented explicitly. The generator must not rely on undocumented Keycloak defaults for these claims.
|
|
|
|
---
|
|
|
|
# Runtime Boundaries
|
|
|
|
The repository's local runtime topology remains unchanged:
|
|
|
|
- `docker-compose.yml` provisions PostgreSQL only
|
|
- Keycloak remains external to this repo's Docker runtime
|
|
|
|
The generator must therefore produce:
|
|
|
|
- runtime documentation for importing/configuring the generated realm import artifact
|
|
- env contracts for frontend and backend
|
|
- validation rules that assume an external but reachable Keycloak server
|