GREACT/KIS-TOiR
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

keycloak init

Browse Source
This commit is contained in:
MaKarin
2026-03-21 16:00:27 +03:00
parent 33521016d3
commit 8d6875f4b0
50 changed files with 2242 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
backend/runtime-rules.md
View File

@@ -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` |