Initial commit

2026-07-23 19:18:34 +02:00
commit 60db30a960
5 changed files with 285 additions and 0 deletions
@@ -0,0 +1,67 @@
+# keycloak/realm-export.json
+
+Realm `scouthub` con feature Organizations abilitata, importato automaticamente
+all'avvio di Keycloak (`--import-realm` nel `docker-compose.yml` alla radice).
+
+Basato su `keycloak/realm.json` (bozza di riferimento), con l'aggiunta del
+ruolo `admin-centrale` richiesto da `POST /gruppi` in `scouthub-home-be`
+(placeholder temporaneo, vedi il TODO in `src/routes/gruppi.routes.ts`).
+
+Contiene già:
+
+- i realm role usati dal backend: `admin-centrale`, `capo-gruppo`,
+  `capo-unita`, `censito`, più il placeholder `manage-organizations`
+- il client scope `organization` (aggiunge id/attributi della Organization
+  nei token OIDC)
+- il client confidential `scouthub-home-be` (service account abilitato,
+  usato dal backend per il flow client-credentials verso le Admin REST API —
+  il suo `clientId`/`secret` devono corrispondere a
+  `KEYCLOAK_ORG_SERVICE_CLIENT_ID`/`_SECRET` in `scouthub-home-be/.env.example`)
+- il client pubblico `scouthub-frontend` (login utente, redirect su
+  `http://localhost:4200/*`)
+
+Passi manuali ancora da fare dopo l'import (non automatizzabili in un realm
+export senza conoscere gli id generati a runtime):
+
+- assegnare al service account di `scouthub-home-be` i client role del
+  client `realm-management`: `manage-organizations`, `manage-users`,
+  `manage-groups`, `view-users` (permessi minimi, non `manage-realm`). Con le
+  Fine-Grained Admin Permissions (26.7+, `admin-fine-grained-authz:v1`, già
+  abilitata via `KC_FEATURES`) si può poi restringere ulteriormente per
+  singola Organization
+- eventuali mapper aggiuntivi sui client per garantire che `email`,
+  `realm_access.roles` e `organization` compaiano nel token come atteso da
+  `src/middleware/authenticate.ts` in `scouthub-home-be` (i default di
+  Keycloak per organization scope e realm roles di solito bastano, ma vanno
+  verificati contro la versione effettivamente in uso)
+
+I passaggi da fare sono:
+1. Apri http://localhost:8081/admin e fai login (admin / admin, realm master).
+2. In alto a sinistra, cambia realm da master a scouthub.
+3. Menu laterale → Clients → clicca su scouthub-home-be.
+4. Vai sul tab "Service account roles" (visibile perché il client ha "Service accounts enabled").
+5. Clicca "Assign role".
+6. Nella finestra che si apre, in alto c'è un filtro impostato su "Filter by realm roles" — cambialo in "Filter by clients".
+7. Cerca/seleziona il client realm-management.
+8. Spunta questi ruoli — attenzione: ho già controllato via API l'elenco reale dei client role disponibili su realm-management in questa istanza Keycloak 26.7, e manage-groups non esiste come ruolo separato in questa versione (probabilmente  
+   la gestione gruppi è coperta da manage-users). Quindi vedrai solo questi 3, spuntali tutti:                                                                                                                                                       
+   - manage-organizations                                                                                                                                                                                                                          
+   - manage-users                                                                                                                                                                                                                                  
+   - view-users
+9. Clicca Assign.
+10. Dopo fatto questo bisogna fare un user admin-centrale
+
+I passaggi da fare per admin-centrale:
+1. Apri http://localhost:8081/admin, login admin/admin, cambia realm in scouthub.
+2. Menu laterale → Users → clicca su movioletto@yahoo.it.
+3. Vai sul tab "Role mapping".
+4. Clicca "Assign role".
+5. Assicurati che il filtro sia su "Filter by realm roles" (dovrebbe esserlo di default per gli utenti normali).
+6. Cerca e seleziona admin-centrale.
+7. Clicca Assign.
+
+⚠️ Il secret del client `scouthub-home-be` (`CAMBIA-QUESTO-SECRET-IN-UN-VAULT`)
+è un placeholder di sviluppo committato in chiaro, coerente con le altre
+credenziali dev del progetto (vedi `.env` alla radice): da sostituire con un
+segreto reale gestito a parte prima di qualunque uso condiviso o di
+produzione.