keycloak init

2026-03-21 16:00:27 +03:00
parent 33521016d3
commit 8d6875f4b0
50 changed files with 2242 additions and 252 deletions
--- a/backend/architecture.md
+++ b/backend/architecture.md
@@ -7,6 +7,7 @@ Backend stack:
 - NestJS
 - Prisma ORM
 - PostgreSQL
+- jose

 The backend is generated from the DSL specification.

@@ -32,6 +33,15 @@ src/
 main.ts
 app.module.ts

+    auth/
+      auth.module.ts
+      guards/
+      decorators/
+      interfaces/
+
+    config/
+      env.validation.ts
+
    modules/

      {entity}/
@@ -105,6 +115,7 @@ Every generated backend must expose a **health endpoint** so that runtime and or
 ## Controller example

 ```typescript
+@Public()
@Controller("health")
 export class HealthController {
  @Get()
@@ -118,6 +129,42 @@ Register the health controller in the root app module (or a dedicated health mod

 ---

+# Authentication and Authorization
+
+The generated backend must include explicit auth infrastructure by default.
+
+Generate:
+
+- `AuthModule`
+- JWT guard
+- roles guard
+- `@Public()`
+- `@Roles()`
+- typed authenticated principal
+- typed env validation for auth/runtime variables
+
+Rules:
+
+1. `/health` must remain public.
+2. Generated CRUD routes must be protected by default.
+3. JWT verification must use issuer + audience + JWKS.
+4. Authorization roles must be extracted only from `realm_access.roles`.
+5. The generated backend must not use deprecated Keycloak-specific Node adapters.
+
+## CRUD RBAC defaults
+
+Apply these defaults to generated CRUD controllers:
+
+- `GET` -> `viewer`, `editor`, `admin`
+- `POST` -> `editor`, `admin`
+- `PATCH` -> `editor`, `admin`
+- `PUT` -> `editor`, `admin`
+- `DELETE` -> `admin`
+
+These defaults must be encoded in generated guards/decorators, not left as informal guidance.
+
+---
+
 # List Endpoint

 List endpoint must support pagination and filters via query parameters.
@@ -247,8 +294,8 @@ See **Controller Rules** above for the rule that :pk must match the entity's pri

 # Environment and runtime

- **Environment variables:** Backend requires at least `DATABASE_URL`. See **backend/runtime-rules.md**.
- **.env:** Generated project must include a `.env` (and `.env.example`) with `DATABASE_URL` so the app starts without runtime errors.
+- **Environment variables:** Backend requires runtime and auth variables. See **backend/runtime-rules.md**.
+- **.env:** Generated project must include a `.env` (and `.env.example`) with database, auth, and CORS variables so the app starts without runtime errors.
 - **PrismaService:** Must follow **backend/prisma-service.md** (OnModuleInit, $connect; no beforeExit).
 - **Prisma client:** Add `"postinstall": "prisma generate"` (or equivalent) to package.json so the client is generated after install.
 - **Migrations:** Document or run `npx prisma migrate dev` after schema generation. See **backend/runtime-rules.md** and **generation/backend-generation.md**.
--- a/backend/runtime-rules.md
+++ b/backend/runtime-rules.md
@@ -10,14 +10,24 @@ The backend **must** have a `.env` file at the project root (e.g. `server/.env`

 ## Required variables

-| Variable     | Required | Description                             |
-| ------------ | -------- | --------------------------------------- |
-| DATABASE_URL | Yes      | PostgreSQL connection string for Prisma |
+| Variable             | Required | Description |
+| -------------------- | -------- | ----------- |
+| PORT                 | Yes      | Backend listen port |
+| DATABASE_URL         | Yes      | PostgreSQL connection string for Prisma |
+| CORS_ALLOWED_ORIGINS | Yes      | Comma-separated SPA origins allowed to call the API |
+| KEYCLOAK_ISSUER_URL  | Yes      | Keycloak issuer URL used for JWT verification |
+| KEYCLOAK_AUDIENCE    | Yes      | Backend audience/client expected in access tokens |
+| KEYCLOAK_JWKS_URL    | No       | Optional explicit JWKS URL |

 ## Example

 ```env
+PORT=3000
 DATABASE_URL="postgresql://postgres:postgres@localhost:5432/toir"
+CORS_ALLOWED_ORIGINS="http://localhost:5173,https://toir-frontend.greact.ru"
+KEYCLOAK_ISSUER_URL="https://sso.greact.ru/realms/toir"
+KEYCLOAK_AUDIENCE="toir-backend"
+# KEYCLOAK_JWKS_URL="https://sso.greact.ru/realms/toir/protocol/openid-connect/certs"
 ```

 ## Generation requirement
@@ -25,7 +35,7 @@ DATABASE_URL="postgresql://postgres:postgres@localhost:5432/toir"
 When generating the backend, **always** create:

 1. **`.env.example`** — with placeholder DATABASE_URL and instructions.
-2. **`.env`** — with the same placeholder so the app can start; user replaces with real values.
+2. **`.env`** — with local development example values so the app can start.

 If the generator does not create `.env`, the first run will fail with:

@@ -33,6 +43,34 @@ If the generator does not create `.env`, the first run will fail with:
 Environment variable not found: DATABASE_URL
 ```

+## Fail-fast requirement
+
+The generated backend must validate required runtime and auth variables at startup.
+
+Rules:
+
+1. Missing required auth variables must stop startup immediately.
+2. The generated backend must not silently fall back to production auth settings in code.
+3. Auth env validation must be implemented explicitly in generated config/bootstrap code.
+
+---
+
+# Authentication Runtime Rules
+
+The generated backend must verify JWTs against Keycloak using:
+
+- issuer
+- audience
+- JWKS
+
+JWKS resolution priority must be exactly:
+
+1. explicit `KEYCLOAK_JWKS_URL`
+2. OIDC discovery
+3. `${issuer}/protocol/openid-connect/certs`
+
+The generated backend must extract authorization roles only from `realm_access.roles`.
+
 ---

 # Prisma Client Generation
@@ -85,10 +123,30 @@ Run after:

 ---

+# CORS Rules
+
+The generated backend must support the SPA -> API bearer-token model explicitly.
+
+Rules:
+
+1. Use `CORS_ALLOWED_ORIGINS` as the allowed origin list.
+2. Allow at minimum these example origins in `.env.example`:
+   - `http://localhost:5173`
+   - `https://toir-frontend.greact.ru`
+3. Allow `Authorization` and JSON content headers.
+4. Expose `Content-Range` because React Admin depends on it.
+5. Do not enable credentials by default.
+
+---
+
 # Summary

-| Requirement     | Action                                                        |
-| --------------- | ------------------------------------------------------------- |
-| DATABASE_URL    | Create `.env` and `.env.example` with DATABASE_URL            |
-| Prisma client   | Run `npx prisma generate`; add `postinstall` script           |
-| Database schema | Document/run `npx prisma migrate dev` after schema generation |
+| Requirement             | Action |
+| ----------------------- | ------ |
+| Runtime env             | Create `.env` and `.env.example` with DB, auth, and CORS variables |
+| Fail-fast config        | Validate required auth/runtime variables at startup |
+| Prisma client           | Run `npx prisma generate`; add `postinstall` script |
+| Database schema         | Document/run `npx prisma migrate dev` after schema generation |
+| JWT verification        | Use issuer + audience + JWKS with explicit resolution priority |
+| Role extraction         | Use only `realm_access.roles` |
+| CORS                    | Support SPA -> API bearer flow and expose `Content-Range` |