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, e riceve indietro gli eventi via webhook. 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.

import { LoginMaster } from "@loginmaster/sdk";

const lm = new LoginMaster({
  projectKey: process.env.LOGINMASTER_PROJECT_KEY,
  tenant: "https://tenant.example.com",
});

async function upsertSubject(externalId: string, roles: string[]) {
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      return await lm.subjects.upsert({ type: "user", externalId, roles });
    } catch (error) {
      if (!isRetryable(error) || attempt === 4) throw error;
      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 — Webhook: eventi in push, firmati

Il polling periodico dell'elenco utenti è la soluzione che funziona con cento utenti e diventa insostenibile con centomila. I webhook rovesciano il flusso: la piattaforma notifica, la tua applicazione reagisce.

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

{
  "url": "https://app.example.com/hooks/loginmaster",
  "events": [
    "subject.authenticated",
    "subject.role_changed",
    "subject.deactivated"
  ]
}

import { verifyWebhook } from "@loginmaster/sdk";

app.post("/hooks/loginmaster", (req, res) => {
  const isValid = verifyWebhook({
    payload: req.rawBody,
    signature: req.headers["x-loginmaster-signature"],
    secret: process.env.LOGINMASTER_WEBHOOK_SECRET,
  });

  if (!isValid) return res.status(401).end();

  // Idempotenza: l'evento può arrivare più di una volta
  if (alreadyProcessed(req.body.id)) return res.status(200).end();

  handleEvent(req.body);
  res.status(200).end();
});

• Valida sempre la firma HMAC-SHA256 sul corpo grezzo della richiesta, prima di deserializzarlo: un endpoint webhook non autenticato è un'API pubblica di scrittura.
• Rendi il consumo idempotente sull'id dell'evento: la consegna 'almeno una volta' è la norma, la consegna 'esattamente una volta' non esiste.
• Rispondi 2xx rapidamente e processa in coda: se il tuo handler impiega trenta secondi, i tentativi ripetuti si accumulano.
• Registra gli eventi ricevuti: servono per la ricostruzione dello stato e come evidenza in un audit.

Passo 7 — Riconciliazione: il passo che quasi nessuno fa

Ogni automazione perde eventi: una finestra di manutenzione, un webhook non consegnato, 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; oggi il ciclo di vita si automatizza via REST API, SDK e webhook, 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 dal consumo del webhook.
• Invia al tuo endpoint un webhook con firma errata: deve essere respinto.
• Consegna lo stesso evento due volte: l'effetto deve essere identico a una sola consegna.
• 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.