Importa & Esporta Utenti
Auris fornisce strumenti di importazione ed esportazione in blocco per i dati utente. Importa utenti da file CSV o JSON quando migri da un altro identity provider, acquisisci un nuovo reparto, o popoli un ambiente di staging. Esporta il tuo database utenti per backup, audit di conformità, o migrazione verso un altro sistema.
Accedi da Console → Impostazioni → Importa / Esporta.
Importare Utenti
Il flusso di importazione ti guida attraverso il caricamento del file, l’anteprima dei dati e l’elaborazione. Le importazioni vengono eseguite in modo asincrono — puoi navigare altrove dalla pagina e controllare i progressi in seguito.
Procedura di Importazione
Clicca Importa Utenti
Nella pagina Importa / Esporta, clicca il pulsante Importa Utenti nella sezione Importazione.
Seleziona il formato del file
Scegli CSV o JSON. Questo indica ad Auris come analizzare il file che stai per caricare.
Carica il tuo file
Trascina e rilascia un file nell’area di caricamento, o clicca Sfoglia per selezionare un file dal tuo computer. La dimensione massima del file è 10 MB.
Visualizza in anteprima i dati analizzati
Auris analizza il file e mostra le prime 10 righe in una tabella di anteprima. Verifica che le intestazioni delle colonne siano rilevate correttamente e che i valori appaiano nei campi giusti.
Mappa le colonne ai campi Auris
Se il tuo file usa nomi di colonne non standard, mappa ogni colonna al campo Auris corrispondente:
| Campo Auris | Obbligatorio | Descrizione |
|---|---|---|
email | Sì | L’indirizzo email dell’utente. Deve essere un formato email valido e univoco nel tenant. |
firstName | No | Nome |
lastName | No | Cognome |
username | No | Username. Se omesso, Auris lo ricava dall’indirizzo email. |
password | No | Password in chiaro. Viene sottoposta a hash (bcrypt) prima dell’archiviazione. Se omessa, l’utente deve usare Password Dimenticata o Magic Link per impostare una password. |
roles | No | Elenco separato da virgole di nomi di ruoli da assegnare. I ruoli devono già esistere nel tenant. |
Clicca Avvia Importazione
Clicca Avvia Importazione per iniziare l’elaborazione. L’importazione viene eseguita in background.
Requisiti del Formato File
Formato CSV
La prima riga deve essere una riga di intestazione con i nomi delle colonne. I valori contenenti virgole devono essere tra virgolette.
email,firstName,lastName,password,roles
[email protected],Alice,Rossi,PasswordSicura123,editor
[email protected],Bob,Bianchi,AltraPassword456,"editor,viewer"
[email protected],Carla,Verdi,,viewerNell’esempio sopra, Carla non ha password — dovrà usare Password Dimenticata o Magic Link per impostarne una.
Formato JSON
Il file deve contenere un array JSON di oggetti utente.
[
{
"email": "[email protected]",
"firstName": "Alice",
"lastName": "Rossi",
"password": "PasswordSicura123",
"roles": ["editor"]
},
{
"email": "[email protected]",
"firstName": "Bob",
"lastName": "Bianchi",
"password": "AltraPassword456",
"roles": ["editor", "viewer"]
},
{
"email": "[email protected]",
"firstName": "Carla",
"lastName": "Verdi",
"roles": ["viewer"]
}
]Le password nei file di importazione vengono sottoposte a hash (bcrypt) prima dell’archiviazione. Non vengono mai archiviate o registrate in chiaro. Gli utenti importati con password possono accedere immediatamente. Gli utenti importati senza password devono usare il flusso Password Dimenticata o Magic Links per creare le credenziali.
Elaborazione dell’Importazione
Dopo aver cliccato Avvia Importazione, l’importazione viene eseguita in modo asincrono. Ogni riga viene elaborata in sequenza:
- L’email viene validata per formato e univocità
- Se è fornita una password, viene sottoposta a hash con bcrypt
- L’utente viene creato in Prisma (database Auris)
- L’utente viene creato in Keycloak (backend di autenticazione)
- Se sono specificati ruoli, l’utente viene assegnato a quei ruoli
- Il contatore di progresso dell’importazione si incrementa
Cronologia Importazioni
La sezione Importazione mostra una tabella storica di tutti i job di importazione:
| Colonna | Descrizione |
|---|---|
| Nome File | Il nome del file caricato |
| Formato | CSV o JSON |
| Stato | Stato corrente |
| Righe Totali | Numero di record utente nel file |
| Successi | Numero di utenti importati con successo |
| Errori | Numero di righe fallite |
| Data | Quando è stata avviata l’importazione |
Stati dell’Importazione
| Stato | Significato |
|---|---|
| In attesa | L’importazione è in coda ma non ha ancora iniziato l’elaborazione |
| In elaborazione | L’importazione è attivamente in corso. Una barra di progresso mostra X di Y utenti elaborati. |
| Completata | Tutte le righe sono state elaborate con successo senza errori |
| Parziale | L’elaborazione è terminata ma alcune righe sono fallite. Clicca per vedere i dettagli degli errori. |
| Fallita | L’importazione non ha potuto essere elaborata affatto (es. file malformato o Keycloak non raggiungibile) |
Visualizzare i Dettagli degli Errori
Clicca qualsiasi importazione con stato Parziale o Fallita per vedere i dettagli degli errori per riga:
| Colonna | Descrizione |
|---|---|
| Numero Riga | Quale riga nel file è fallita |
| L’indirizzo email da quella riga | |
| Errore | Cosa è andato storto |
Errori comuni per riga:
| Errore | Causa |
|---|---|
| Email già esistente | Un utente con questa email è già nel tenant |
| Formato email non valido | L’indirizzo email non è in un formato valido |
| Ruolo non trovato: “admin” | Il ruolo specificato non esiste nel tenant |
| Errore Keycloak | Keycloak ha rifiutato la creazione dell’utente |
| Campo obbligatorio mancante: email | La colonna email è vuota per questa riga |
Le importazioni creano utenti sia in Prisma che in Keycloak. Se Keycloak non è raggiungibile durante l’importazione, le righe interessate falliranno. Le righe importate con successo (già in entrambi i sistemi) non vengono annullate. Riesegui l’importazione dopo il ripristino di Keycloak — gli utenti esistenti verranno saltati con un errore “email già esistente”, e solo le righe precedentemente fallite verranno create.
Esportare Utenti
Esporta il tuo database utenti in un file CSV o JSON per backup, migrazione o conformità.
Procedura di Esportazione
Clicca Esporta Utenti
Nella pagina Importa / Esporta, clicca il pulsante Esporta Utenti nella sezione Esportazione.
Seleziona il formato di esportazione
Scegli CSV o JSON.
Clicca Avvia Esportazione
Clicca Avvia Esportazione. L’esportazione viene eseguita in background.
Scarica il file
Quando l’esportazione è completata, nella tabella cronologica delle esportazioni appare un pulsante Scarica. Clicca per scaricare il file.
Campi Esportati
L’esportazione include i seguenti campi per ogni utente:
| Campo | Descrizione |
|---|---|
email | L’indirizzo email dell’utente |
firstName | Nome |
lastName | Cognome |
username | Username |
roles | Elenco separato da virgole dei nomi dei ruoli assegnati |
enabled | Se l’account è attivo (true / false) |
createdAt | Timestamp di creazione account (ISO 8601) |
lastLoginAt | Timestamp dell’accesso più recente (ISO 8601), o vuoto se l’utente non ha mai effettuato l’accesso |
Le password non vengono mai incluse nelle esportazioni. Questa è una misura di sicurezza deliberata. Se hai bisogno di migrare utenti verso un altro sistema, gli utenti dovranno reimpostare le password nel nuovo sistema.
Cronologia Esportazioni
La sezione Esportazione mostra una tabella storica di tutti i job di esportazione. I file di esportazione vengono eliminati automaticamente 24 ore dopo la generazione.
Riferimento API
Le operazioni di importazione ed esportazione sono disponibili anche tramite l’API REST.
/api/users/import//api/users/import//api/users/import/:id/api/users/export//api/users/export//api/users/export/:id/downloadBest Practice
-
Testa prima con un file piccolo. Prima di importare 10.000 utenti, prova con un file di 5-10 utenti per verificare che la mappatura delle colonne e i nomi dei ruoli siano corretti.
-
Crea i ruoli in anticipo. L’importazione non crea ruoli automaticamente. I nomi dei ruoli referenziati nel file di importazione devono già esistere in Console → Ruoli.
-
Usa una formattazione email coerente. Auris tratta gli indirizzi email come case-insensitive, ma la maiuscola originale viene preservata.
-
Pianifica le importazioni di grandi dimensioni nelle ore di basso traffico. Ogni utente importato attiva una chiamata API Keycloak.
-
Tieni al sicuro i file di esportazione. Anche se le esportazioni non contengono password, contengono indirizzi email, nomi e assegnazioni di ruoli. Tratta i file di esportazione come dati sensibili.
Permessi
| Permesso | Descrizione |
|---|---|
manage:users | Richiesto sia per importare che per esportare utenti. |
Guide Correlate
- Gestione Utenti — Creazione e gestione dei singoli utenti nella Console
- Utenti & Ruoli — Gestione utenti e ruoli nella Console
- Provisioning SCIM — Provisioning automatizzato da IdP aziendali come alternativa all’importazione manuale