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