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.
@@ -0,0 +1,64 @@
+{
+  "realm": "scouthub",
+  "enabled": true,
+  "organizationsEnabled": true,
+  "sslRequired": "external",
+  "registrationAllowed": true,
+  "registrationEmailAsUsername": true,
+  "loginWithEmailAllowed": true,
+  "resetPasswordAllowed": true,
+  "verifyEmail": false,
+
+  "roles": {
+    "realm": [
+      { "name": "admin-centrale", "description": "Placeholder temporaneo: crea nuovi gruppi scout (Organization). Vedi TODO in src/routes/gruppi.routes.ts" },
+      { "name": "capo-gruppo", "description": "Gestisce il proprio gruppo scout (Organization): membri, inviti, ruoli" },
+      { "name": "capo-unita", "description": "Gestisce attivita' e materiali della propria branca" },
+      { "name": "censito", "description": "Accesso in sola consultazione" },
+      { "name": "manage-organizations", "description": "Placeholder locale: il ruolo reale e' il client role manage-organizations su realm-management" }
+    ]
+  },
+
+  "clients": [
+    {
+      "clientId": "scouthub-home-be",
+      "name": "Servizio di gestione gruppi scout (org-service)",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": false,
+      "standardFlowEnabled": false,
+      "directAccessGrantsEnabled": false,
+      "serviceAccountsEnabled": true,
+      "clientAuthenticatorType": "client-secret",
+      "secret": "CAMBIA-QUESTO-SECRET-IN-UN-VAULT",
+      "attributes": {
+        "note": "Usato solo server-to-server dal backend org-service verso le Admin REST API. Non esporre mai il secret al frontend."
+      }
+    },
+    {
+      "clientId": "scouthub-frontend",
+      "name": "Frontend Angular Scouthub",
+      "enabled": true,
+      "protocol": "openid-connect",
+      "publicClient": true,
+      "standardFlowEnabled": true,
+      "directAccessGrantsEnabled": false,
+      "redirectUris": [
+        "http://localhost:4200/*",
+        "http://localhost:4201/*"
+      ],
+      "webOrigins": [
+        "http://localhost:4200",
+        "http://localhost:4201"
+      ],
+      "defaultClientScopes": [
+        "openid",
+        "basic",
+        "roles",
+        "profile",
+        "email",
+        "organization"
+      ]
+    }
+  ]
+}