# JB4.2 - Agganciare un servizio nuovo

**In una frase.** Un servizio nuovo entra nell'accesso unico rispettando poche regole fisse: da quel momento compare da solo nella pagina Ruoli e permessi, con gli stessi quattro livelli.

ADSWnext cresce un servizio alla volta. Se ognuno inventasse i suoi utenti e i suoi permessi, in pochi mesi si tornerebbe al punto di partenza. Con un contratto unico chi amministra non deve imparare niente di nuovo: trova una scheda in più, fatta come le altre.

**Oggi sono agganciati** ADEnext, GPEnext e SIGEAnext, che usa gli stessi agganci di ADEnext. L'Assistente dei dati non lo è ancora.

Cosa deve fare un servizio per entrare:

1. **Stare dietro il Gateway.** Le richieste arrivano solo da lì, già controllate. Il servizio non chiede password e non ne conserva.
2. **Leggere i ruoli nello stesso modo degli altri.** Dal lasciapassare prende tutti i ruoli della persona e li traduce in un livello con le stesse regole: vale il più alto, lo Staff conta solo dove è acceso.
3. **Dichiarare cosa concede.** Un elenco di capacità, ognuna con il livello minimo che serve. È ciò che la pagina mostra con le spunte.
4. **Tenere la sua tabella dei ruoli**, con i quattro livelli già pronti.
5. **Rispondere alle stesse domande.** Quali ruoli conosci, cosa dà ogni livello, che livello ha chi sta chiedendo. Sono uguali in ogni servizio.
6. **Farsi elencare.** Una riga nel registro dei servizi dell'applicazione. La pagina **Ruoli e permessi** e il **Ruolo di prova** lo trovano da soli; se è spento lo mostrano spento, con il motivo.

Un test uguale in tutti i servizi controlla che le regole diano gli stessi risultati ovunque.

<p class="callout warning">**Attenzione.** Un servizio non deve mai decidere guardando il nome di un ruolo scritto nel codice. Decide sulle sue capacità: è questo che permette a chi amministra di cambiare i permessi senza toccare il programma.</p>

<p class="callout info">**Per chi sviluppa.**  
• Non c'è una libreria comune: i file sono gemelli e si copiano cambiando solo il `package` (`Livello`, `Capacita`, `Origine`, `RegoleRuoli`, `RuoliException`, più il proprio `CapacitaServizio`).  
• Contratto: `GET /ruoli`, `GET /ruoli/livelli`, `GET /me/permessi`, e `/admin/ruoli` per chi ha la capacità `ruoli`. Il Gateway antepone `/api/<servizio>`.  
• Test di contratto: `RuoliContrattoTest`. Registro: `SERVIZI_CON_RUOLI` in `frontend/shell/src/shared/auth/ruolo-prova.ts`.  
• Passi completi: `docs/guide/sviluppo/ruoli-centrali/README.md`. Rotte e sicurezza del Gateway: `.claude/skills/gateway-auth/SKILL.md`. </p>

<p class="callout info">**Per approfondire.**  
• Login unico con Keycloak: `docs/guide/amministrazione/login-unico-keycloak/README.md`  
• Integrazione Autenticazione JWT Angular + API Gateway: `docs/guide/sviluppo/GUIDA-AUTENTICAZIONE-JWT.md`</p>