Come automatizzare il provisioning e il ciclo di vita degli utenti tramite API REST e SDK

Automatizzare il provisioning significa smettere di creare utenti a mano e far governare il ciclo di vita da una sorgente autorevole — il sistema HR, la directory aziendale, il CRM — che dialoga con la piattaforma di identità via REST API e SDK. In pratica: un POST idempotente alla creazione, un aggiornamento dei ruoli al cambio di mansione, una disattivazione all'uscita, e una riconciliazione periodica che verifica che lo stato reale corrisponda a quello atteso. È l'ultimo punto quello che distingue un'automazione funzionante da una che sembra funzionare.

Il modello joiner-mover-leaver

Il ciclo di vita di un'identità ha tre eventi, e il valore dell'automazione è distribuito in modo molto sbilanciato fra loro. La creazione è quella che si automatizza per prima perché è visibile: se il nuovo assunto non ha l'account il primo giorno, qualcuno se ne lamenta. La disattivazione è quella che conta per la sicurezza, ed è anche l'unica che nessuno segnala quando manca: un account attivo di una persona uscita sei mesi fa non genera ticket.

Passo 1 — Scegli la sorgente autorevole

Ogni identità deve avere un solo sistema che decide se esiste. Senza questa scelta, il provisioning automatico moltiplica gli errori invece di eliminarli, perché due sistemi si sovrascrivono a vicenda.

• Dipendenti: il sistema HR, non la directory. La directory è già una proiezione.
• Collaboratori e fornitori: il sistema che gestisce i contratti, con una data di fine obbligatoria.
• Utenti clienti in una SaaS B2B: il tenant del cliente, spesso via SSO federato con la sua directory.
• Dispositivi e agenti automatici: l'inventario o il sistema di deploy, mai una persona.

Per collaboratori esterni e fornitori la data di fine non è burocrazia: è la sola cosa che rende automatica la disattivazione di un'identità per cui nessun processo HR emetterà mai un evento di uscita.

Passo 2 — L'identificatore esterno stabile

La correlazione fra sorgente autorevole e piattaforma di identità deve poggiare su un identificatore che non cambia mai. L'email cambia — cognomi, riorganizzazioni, fusioni di dominio — e ogni cambio produce un account duplicato con storico perso.

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

{
  "type": "user",
  "externalId": "hr-4821",
  "roles": ["member"]
}

HTTP/1.1 201 Created
{
  "subjectId": "sub_5d1b8e",
  "type": "user",
  "externalId": "hr-4821",
  "status": "active"
}

L'externalId — il codice dipendente HR, l'object ID della directory, l'ID contratto — è la chiave con cui riconoscerai quella persona per sempre. Il subjectId restituito è l'identificativo interno da usare in tutte le operazioni successive.

Passo 3 — Creazione idempotente

Un'integrazione di provisioning viene rieseguita: per un retry dopo un timeout, per una ripartenza di un job, per un evento consegnato due volte. Se la creazione non è idempotente, ognuno di questi casi è un duplicato o un errore che blocca la coda.

1. 1Prima di creare, cerca il soggetto per externalId; se esiste, esegui un aggiornamento invece di una creazione.
2. 2Tratta il conflitto (409) come esito accettabile e non come errore fatale del job.
3. 3Registra l'esito di ogni operazione con l'externalId, così un job interrotto riparte dal punto giusto.
4. 4In caso di errore 5xx o di limite di frequenza, applica un backoff esponenziale con jitter invece di ripetere subito.
5. 5Non considerare completata l'operazione finché non hai una risposta: un timeout non significa che il server non abbia eseguito.

async function provisionSubject(externalId: string, roles: string[]) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(
      "https://api.loginmaster.it/v1/projects/prj_12ab/subjects",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.LOGINMASTER_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ type: "user", externalId, roles }),
      },
    );
    if (res.status === 201 || res.status === 409) return res; // 409 = già presente
    if (res.status < 500 && res.status !== 429) throw new Error(await res.text());
    await sleep(2 ** attempt * 250 + Math.random() * 250);
  }
}

Passo 4 — Il cambio di ruolo

Il cambio di ruolo è l'evento che più spesso resta manuale, ed è quello che genera il rilievo più fastidioso in un audit: persone con permessi che non corrispondono più alla mansione. Due regole tecniche lo risolvono.

• L'aggiornamento dei ruoli è una sostituzione dell'insieme, non un'aggiunta: l'API riceve la lista completa dei ruoli attesi.
• I ruoli effettivi si ricalcolano a ogni autenticazione a partire dai gruppi e dagli attributi correnti, non solo alla creazione dell'account.

La seconda regola è quella che rende reale la revoca: senza ricalcolo, togliere un utente da un gruppo nella directory non produce alcun effetto finché quel token non scade, e in alcune architetture nemmeno dopo. La mappatura gruppi → ruoli è trattata nella guida al SSO federato.

Passo 5 — Deprovisioning e finestra di esposizione

Il deprovisioning ha due tempi, e vanno misurati separatamente: quanto passa fra l'evento nella sorgente autorevole e la disattivazione dell'identità, e quanto passa fra la disattivazione e la cessazione effettiva delle sessioni già aperte.

Per gli utenti federati la finestra si chiude da sola: quando l'account nella directory aziendale viene disattivato, i servizi federati smettono di autenticarlo. È uno dei motivi per cui conviene federare anche quando non è un requisito esplicito del cliente.

Passo 6 — Sessioni, API key e sincronizzazione senza webhook

Su LoginMaster i webhook di lifecycle sono in roadmap e oggi non sono disponibili: la piattaforma non notifica in push la tua applicazione quando un soggetto viene disattivato. Lo diciamo prima che lo scopra il tuo collaudo. C'è un secondo limite da conoscere: la disattivazione di un soggetto blocca i nuovi login, ma non revoca in modo atomico le sessioni già aperte e le API key associate. Il flusso di uscita va quindi costruito con passi espliciti.

1. 1Disattiva il soggetto: da quel momento non ottiene nuovi token.
2. 2Revoca in un passo separato le API key associate al soggetto o alle sue integrazioni, e registra l'esito.
3. 3Nell'applicazione, verifica il token a doppia firma a ogni richiesta sensibile invece di fidarti della sessione locale: un token non più valido chiude l'accesso al primo controllo.
4. 4Riduci la durata dei token sui progetti sensibili: è il limite superiore della finestra di esposizione.
5. 5Per gli utenti federati, disattiva l'account in Entra ID o Google Workspace: il login federato successivo fallisce senza interventi sulla piattaforma.
6. 6Lascia alla riconciliazione del passo 7 il compito di intercettare ciò che i passi precedenti hanno mancato.

const session = await lm.verifyToken(token);

if (!session.valid) {
  // Soggetto disattivato o token scaduto: chiudi la sessione locale
  return res.status(401).end();
}

Quando i webhook saranno rilasciati, sostituiranno il controllo applicativo sul percorso veloce ma non la riconciliazione, che resta necessaria con qualunque meccanismo di notifica. Lo stato aggiornato è su provisioning utenti e nella tabella disponibile oggi / in roadmap.

Passo 7 — Riconciliazione: il passo che quasi nessuno fa

Ogni automazione perde eventi: una finestra di manutenzione, un job di sincronizzazione saltato, un job interrotto, un'operazione manuale d'emergenza mai riportata nella sorgente. La riconciliazione periodica è il controllo che trasforma un'automazione plausibile in un'automazione verificabile.

1. 1Ogni notte estrai l'elenco dei soggetti attivi dalla piattaforma e l'elenco delle identità attese dalla sorgente autorevole.
2. 2Calcola tre differenze: presenti in piattaforma ma non attesi (account orfani), attesi ma assenti, presenti con ruoli divergenti.
3. 3Correggi automaticamente le divergenze a basso rischio e segnala le altre a una persona.
4. 4Conserva il report: è esattamente l'evidenza che un auditor chiede per il controllo sulla revisione periodica degli accessi.
5. 5Fai in modo che un report vuoto sia il caso normale; se è sempre pieno, il problema è nel flusso primario, non nella riconciliazione.

Cosa l'automazione non deve poter fare

C'è un'operazione che molte piattaforme espongono nelle API di amministrazione e che LoginMaster deliberatamente non espone: la gestione delle credenziali. Non esiste un endpoint che restituisca l'hash di una password, che imposti una password per conto dell'utente o che disattivi il suo secondo fattore.

La conseguenza operativa è netta: una API key compromessa consente di creare, aggiornare e disattivare soggetti — operazioni tracciate e reversibili — ma non consente in alcun caso di impersonare un utente. È lo stesso vincolo architetturale descritto su autenticazione zero-knowledge, applicato al piano di amministrazione.

E lo SCIM?

SCIM è lo standard di provisioning che i grandi identity provider usano per spingere utenti e gruppi verso le applicazioni. È utile quando l'integrazione deve essere configurata da un amministratore che non scrive codice. Su LoginMaster il supporto SCIM è in roadmap, come i webhook di lifecycle; oggi il ciclo di vita si automatizza via REST API e SDK, che coprono gli stessi casi d'uso con più controllo sulla logica di mappatura e sulla gestione degli errori. Lo stato aggiornato è sulla pagina provisioning utenti.

Confronto fra approcci

Checklist di collaudo

• Riesegui lo stesso provisioning due volte: nessun duplicato, nessun errore bloccante.
• Simula un timeout dopo l'invio: il retry non deve creare un secondo soggetto.
• Cambia ruolo a un utente e verifica che i permessi precedenti siano rimossi, non sommati.
• Disattiva un utente e misura quanto passa prima che un nuovo login venga rifiutato.
• Verifica che una sessione già aperta venga chiusa alla prima richiesta sensibile dopo la disattivazione.
• Verifica che le API key del soggetto disattivato siano state revocate dal passo esplicito e non funzionino più.
• Riesegui lo stesso job di uscita due volte: l'effetto deve essere identico a una sola esecuzione.
• Esegui la riconciliazione su dati volutamente divergenti e verifica che il report li intercetti.

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. Gli endpoint e gli esempi riportati sono quelli documentati su Integrazione, dove si trovano anche i quickstart completi per TypeScript e .NET. Per discutere un' integrazione specifica: contatti.