scouthub/keycloak/README.md

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 richiesto da POST /gruppi e GET /gruppi in scouthub-home-be: creazione/elenco diretti restano riservati ad admin, mentre un utente normale passa dal flusso self-service di richiesta creazione gruppo (POST /richieste-creazione-gruppo), che alla review positiva invoca la stessa createGruppo() internamente.

Contiene già:

• i realm role usati dal backend, in gerarchia composite (admin include capo-gruppo include capo-unita include capo include censito; admin include anche moderatore): admin, capo-gruppo, capo-unita, capo, censito, moderatore, 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, condiviso da tutti i frontend Angular del progetto, redirect su http://localhost:7000-7003/*)

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

I passaggi da fare per admin:

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.
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.