Skip to Content

Importazione ed Esportazione Utenti

Auris fornisce un sistema asincrono di importazione/esportazione in massa per operazioni di onboarding o migrazione su larga scala. Puoi caricare un file CSV o JSON, monitorare l’avanzamento come job e scaricare un file di export con i dati degli utenti attuali.

Tutti i job vengono elaborati in modo asincrono — se stai importando migliaia di utenti, non devi tenere aperta la connessione.

Importazione di Utenti

Formati di File Supportati

CSV

La prima riga deve essere una riga di intestazione. Le colonne riconosciute sono:

ColonnaObbligatoriaDescrizione
email✅Indirizzo email dell’utente (deve essere univoco)
usernameNoSeparato dall’email; generato automaticamente se assente
firstNameNo
lastNameNo
passwordNoTesto in chiaro — viene subito hashato. Se assente, l’utente viene creato senza credential.
rolesNoPipe-separated: admin|viewer
email,username,firstName,lastName,password,roles
[email protected],alice,Alice,Rossi,SecurePass1!,admin|viewer
[email protected],bob,Roberto,Bianchi,,viewer

JSON

Un array di oggetti con la stessa struttura dei campi CSV:

[
  {
    "email": "[email protected]",
    "username": "alice",
    "firstName": "Alice",
    "lastName": "Rossi",
    "password": "SecurePass1!",
    "roles": ["admin", "viewer"]
  },
  {
    "email": "[email protected]",
    "firstName": "Roberto",
    "lastName": "Bianchi",
    "roles": ["viewer"]
  }
]

Le password vengono trasmesse tramite HTTPS e vengono subito hashate lato server usando l’algoritmo di hashing di Keycloak. Non vengono mai memorizzate in chiaro. Non includere password in file che potrebbero essere memorizzati in sistemi di gestione documenti non sicuri.

Eseguire un’Importazione

Carica il file

POST/api/users/importRequires: manage:users

Carica un file di importazione CSV o JSON. Restituisce un job ID usato per monitorare l’avanzamento.

Invia come multipart/form-data con il file nel campo file:

curl -X POST https://api.tuaapp.com/api/users/import \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected];type=text/csv"

Risposta:

{
  "jobId": "import_01jk9x...",
  "status": "PENDING",
  "totalRows": 250,
  "createdAt": "2025-11-15T09:00:00Z"
}

Monitora l’avanzamento del job

GET/api/users/import/[id]Requires: manage:users

Recupera lo stato di un job di importazione specifico.

GET/api/users/importRequires: manage:users

Elenca tutti i job di importazione, con stato e riepilogo degli errori.

Stati del job:

StatoDescrizione
PENDINGJob accodato, elaborazione non ancora iniziata
PROCESSINGImportazione delle righe in corso
COMPLETEDTutte le righe importate con successo
PARTIALAlcune righe sono fallite (vedi errorCount)
FAILEDJob terminato con un errore irrecuperabile (es. formato file non valido)

Revisiona i risultati

Una volta che il job raggiunge COMPLETED o PARTIAL, la risposta di stato include il conteggio degli errori e i dettagli per riga:

{
  "jobId": "import_01jk9x...",
  "status": "PARTIAL",
  "totalRows": 250,
  "successCount": 247,
  "errorCount": 3,
  "errors": [
    { "row": 14, "email": "[email protected]", "reason": "Email già esistente" },
    { "row": 37, "email": "invalido-email", "reason": "Formato email non valido" },
    { "row": 102, "email": "[email protected]", "reason": "Username 'bob' già in uso" }
  ]
}

Comportamento dell’Importazione

  • Email duplicate: skippate silenziosamente; l’utente esistente non viene modificato.
  • Password assente: l’utente viene creato in stato disabled-credentials (può fare login solo tramite link magici o SSO finché non imposta una password).
  • Assegnazione ruoli: i ruoli vengono assegnati dopo la creazione dell’utente. Se un nome ruolo non esiste, quella riga fallisce.
  • Elaborazione transazionale: le righe vengono elaborate indipendentemente — un fallimento su una riga non fa rollback di quelle già importate con successo.

Esportazione degli Utenti

POST/api/users/exportRequires: manage:users

Avvia un job di esportazione. Restituisce un job ID. Il file di export viene generato in modo asincrono.

GET/api/users/exportRequires: manage:users

Elenca tutti i job di esportazione con stato e data di scadenza.

GET/api/users/export/[id]/downloadRequires: manage:users

Scarica il file di export completato. Restituisce un CSV con tutti i campi esportabili. Disponibile finché il file non è scaduto.

Campi di Esportazione

Il file CSV di export include le seguenti colonne:

CampoDescrizione
idUUID interno dell’utente Auris
emailIndirizzo email
usernameUsername (se impostato)
firstName
lastName
enabledtrue o false
rolesElenco separato da pipe dei ruoli assegnati
createdAtTimestamp ISO 8601
lastLoginTimestamp ISO 8601, o vuoto se l’utente non ha mai fatto login
metadataSerializzato come stringa JSON

Gli hash delle password non vengono mai inclusi negli export, indipendentemente dalle autorizzazioni. Se stai migrando utenti verso un altro sistema di autenticazione, dovrai forzare un reset della password o usare un metodo di autenticazione alternativo.

I file di export scadono dopo 7 giorni. Controlla il campo expiresAt nella risposta del job. Dopo la scadenza, il file viene eliminato automaticamente — dovrai avviare un nuovo export.

Importare/Esportare dalla Console

Puoi gestire importazioni ed esportazioni direttamente dalla Console Admin senza usare l’API.

Per importare:

  1. Vai su Utenti → Importa Utenti.
  2. Trascina un file CSV o JSON nell’area di upload (o clicca per navigare).
  3. Una finestra di anteprima mostra le prime 10 righe analizzate — verifica che le colonne siano correttamente mappate.
  4. Clicca “Avvia Importazione”. Appare una barra di avanzamento che si aggiorna in tempo reale.
  5. Dopo il completamento, un riepilogo mostra le righe riuscite/fallite con i dettagli degli errori.

Per esportare:

  1. Vai su Utenti → Esporta Utenti.
  2. Clicca “Genera Export”. Il job viene accodato.
  3. Una volta completato, appare il pulsante “Scarica CSV”. Il file rimane disponibile per 7 giorni.

Permessi Richiesti

Tutte le operazioni di importazione ed esportazione richiedono il permesso manage:users.

Pagine Correlate

Architettura