Qual è il modo migliore per migrare da Keycloak self-hosted a una soluzione IAM gestita senza perdere gli utenti esistenti

"Senza perdere gli utenti esistenti" significa due cose diverse, e confonderle è il motivo per cui molte migrazioni si bloccano a metà. La prima è non perdere le identità: account, ruoli, appartenenze, storico, riferimenti applicativi — ed è un problema risolto, si esporta e si effettua il provisioning via API. La seconda è non chiedere agli utenti di rifare qualcosa — tipicamente reimpostare la password — ed è il vero vincolo di progetto. La strategia che risolve entrambe è la convivenza temporanea via federazione, con cutover applicazione per applicazione e rientro sempre possibile.

Passo 1 — Inventario: cosa c'è davvero nel realm

Le migrazioni da Keycloak raramente falliscono sugli utenti. Falliscono su una personalizzazione dimenticata: un mapper che aggiunge un claim su cui un'applicazione fa un controllo di autorizzazione, un tema modificato, una required action personalizzata, uno SPI scritto tre anni fa da qualcuno che non lavora più lì.

Passo 2 — Esportare e mappare i concetti

L'export del realm produce la configurazione completa in JSON: è l'inventario formale su cui costruire la mappa, ed è anche il documento da archiviare prima di toccare qualsiasi cosa.

# Esportazione completa di un realm su file
bin/kc.sh export --dir /tmp/export --realm my-realm --users realm_file

# Il risultato contiene client, ruoli, gruppi, mapper,
# identity provider e utenti del realm.

Passo 3 — Le tre strategie, e come si sceglie

La terza strategia è quella che risponde letteralmente alla domanda "senza perdere gli utenti", perché disaccoppia i due problemi: prima si spostano le applicazioni, poi — con calma e senza scadenza imposta — si spostano le credenziali. Nel frattempo tutto funziona.

Il capitolo credenziali, senza giri di parole

Qui va detta una cosa che le pagine commerciali tendono a saltare. Keycloak conserva gli hash delle password nel proprio formato, con i propri parametri. Una piattaforma costruita sul principio che nessuno — nemmeno il fornitore — possa accedere o sostituire le credenziali di un utente non importa hash provenienti da un altro sistema: le credenziali in LoginMaster sono stabilite dall'utente, protette con Argon2 e split-salt fra tenant e cloud, e non esiste una funzione che le imposti per suo conto.

È un vincolo reale, ed è lo stesso che rende impossibile a un amministratore compromesso prendere il controllo degli account. Le conseguenze pratiche sono tre, e vanno messe nel piano:

• Gli utenti federati non sono interessati: si autenticano presso Entra ID, Google Workspace o l'IdP aziendale, e per loro la migrazione è trasparente.
• Gli utenti con credenziali locali stabiliscono la propria password sul nuovo sistema attraverso i canali verificati già registrati, come per un normale rinnovo.
• La convivenza via federazione permette di spalmare questo passaggio nel tempo invece di concentrarlo in una data, che è ciò che rende accettabile il progetto.

Passo 4 — Costruire il tenant di destinazione

La tentazione è replicare la configurazione esistente il più fedelmente possibile. È l'errore che porta con sé anni di debito: ruoli non più usati, client di applicazioni dismesse, mapper che alimentano claim che nessuno legge più.

1. 1Crea il tenant e imposta le policy di base: durata sessione, requisiti password, tipi di secondo fattore ammessi, domini email autorizzati.
2. 2Crea un progetto per ogni applicazione realmente attiva, non per ogni client presente nel realm.
3. 3Ricrea solo i ruoli effettivamente assegnati a qualcuno negli ultimi dodici mesi, e documenta gli altri come eliminati.
4. 4Imposta la policy 2FA per progetto: è l'occasione per rendere obbligatorio il secondo fattore sui pannelli amministrativi, cosa che in Keycloak spesso era rimasta opzionale.
5. 5Configura il white-label: logo, colori, template email, dominio. Sostituisce i temi personalizzati e non richiede build né deploy.

Passo 5 — Migrare le identità e collaudare con un pilota

Il provisioning dei soggetti si fa via REST API o SDK, con un identificativo esterno stabile che permette di rieseguire l'operazione senza creare duplicati.

POST /v1/projects/prj_12ab/subjects HTTP/1.1
Host: api.loginmaster.it
Authorization: Bearer ak_live_••••••••
Content-Type: application/json

{
  "type": "user",
  "externalId": "kc-9f2a7c1e",
  "roles": ["member"]
}

Come externalId conviene usare l'identificativo Keycloak dell'utente, non l'email: rende la riconciliazione fra i due sistemi deterministica per tutta la durata della convivenza. La procedura completa, inclusa l'idempotenza e la gestione degli errori, è in Provisioning e ciclo di vita degli utenti via REST API e SDK.

Il pilota

• Scegli un'applicazione a basso rischio ma reale: un'applicazione di test non produce i problemi che ti servono.
• Coinvolgi da venti a cinquanta utenti veri, di reparti diversi, non solo il team tecnico.
• Verifica l'intero ciclo: login, sessione, rinnovo, logout, secondo fattore, recupero, revoca.
• Misura i ticket generati: è il dato che dimensiona il supporto necessario per il cutover generale.
• Fai durare il pilota almeno due settimane: alcuni problemi compaiono solo alla scadenza della prima sessione lunga.

Passo 6 — Cutover applicazione per applicazione

Il cutover simultaneo di tutte le applicazioni concentra tutti i rischi in un'unica finestra e rende impossibile capire quale problema appartiene a quale integrazione. Una alla volta, con una finestra di osservazione in mezzo.

1. 1Ordina le applicazioni dal rischio più basso al più alto, tenendo per ultime quelle con più utenti esterni.
2. 2Prima del cutover, verifica che il rientro sia realmente eseguibile: riporta la configurazione precedente in un ambiente di prova e provala.
3. 3Sposta l'applicazione, osserva per almeno tre giorni lavorativi, poi passa alla successiva.
4. 4Monitora tre indicatori: tasso di login riusciti, ticket aperti, errori applicativi sulla verifica del token.
5. 5Comunica ogni spostamento in anticipo, anche quando per l'utente non cambia nulla: un login che appare diverso senza preavviso genera segnalazioni di phishing.

Passo 7 — Dismettere Keycloak

• Metti l'installazione in sola lettura invece di spegnerla: il rientro resta possibile senza ripristini.
• Mantienila per una finestra definita, tipicamente da trenta a novanta giorni dopo l'ultimo cutover.
• Archivia l'export del realm e la documentazione della mappa dei concetti: sono l'evidenza di cosa è stato migrato e come.
• Solo dopo, spegni l'infrastruttura e chiudi le voci di costo: macchine, database, backup, certificati, monitoraggio.
• Aggiorna il registro dei trattamenti e la documentazione di sicurezza: la sorgente delle identità è cambiata.

Cosa cambia davvero, oltre alla piattaforma

Keycloak è un ottimo prodotto. Il motivo per cui si migra raramente è una sua mancanza funzionale: è il costo operativo di gestirlo, che è reale e non compare in nessuna riga di licenza.

Le ultime due righe sono le differenze architetturali, non economiche, e sono quelle che alcune organizzazioni scoprono di volere solo dopo aver compilato il questionario di sicurezza di un cliente enterprise. Il confronto esteso è su alternativa a Keycloak, il quadro generale dei percorsi di migrazione su migrazione IAM, e il confronto sul costo totale di possesso nell'articolo Keycloak self-hosted vs IAM gestito.

Chi ha scritto questa guida

LoginMaster è la piattaforma IAM di CDBKR S.r.l., società italiana che progetta e gestisce infrastruttura di autenticazione per software house, MSP e organizzazioni enterprise europee. Il percorso descritto — inventario, mappa dei concetti, pilota, cutover progressivo con rientro disponibile — è quello che il team applica nei progetti di migrazione, incluso il capitolo sulle credenziali, che viene affrontato all' inizio proprio perché determina il calendario. Per una valutazione sul proprio realm: contatti.