Migrare da Auth0 a FoxIDs

Trasferisci gli accessi da Auth0 a FoxIDs con l’approccio di migrazione adatto a ogni connessione. Importa gli utenti del database con gli hash delle password bcrypt oppure consenti loro di scegliere una nuova password. Importa gli utenti senza password e abilita i codici monouso. Per gli accessi social e aziendali, configura metodi di autenticazione FoxIDs che considerino attendibili i provider di identità esterni.

Questa guida tecnica descrive configurazione delle applicazioni, importazione degli utenti e associazione degli account per le connessioni Auth0 a database, senza password via e-mail/SMS, social e aziendali.

Per gli utenti del database e senza password, converti l’esportazione Auth0 verificata in un file CSV e usa FoxIDs Seed Tool per caricare gli utenti in blocco in FoxIDs. Gli esempi CSV seguenti mostrano i campi per ogni approccio di migrazione.

Scegli un metodo per ogni gruppo prima di preparare l’importazione:

Gli utenti importati con e senza password si autenticano localmente in FoxIDs. Gli utenti social e aziendali si autenticano presso il provider di identità collegato.

Preparare la destinazione e l’applicazione

Un ambiente di test dedicato permette di provare la migrazione con un piccolo gruppo di utenti prima del passaggio in produzione. I passaggi di configurazione sono:

1. Se desideri un dominio personalizzato, configuralo e verificalo nel tenant prima di configurare applicazioni e provider di identità esterni. Usa gli URL FoxIDs risultanti per tutta la migrazione. Modificare il dominio in seguito richiede l’aggiornamento delle configurazioni esterne, inclusi gli URL di autorità o metadati delle applicazioni e gli URL di callback e disconnessione dei provider.
2. Ogni ambiente dispone di un metodo di autenticazione Login predefinito chiamato login. Personalizza branding e interfaccia di accesso per ottenere l’aspetto desiderato e adatta le opzioni di accesso agli utenti importati.
3. Crea i metodi di autenticazione che collegano gli utenti social e aziendali ai loro provider esterni, seguendo la sezione di migrazione pertinente riportata di seguito.
4. Configura l’applicazione, gli URL di reindirizzamento consentiti, il comportamento di disconnessione e le API che accettano i suoi token di accesso.

FoxIDs Cloud offre l’invio di e-mail e SMS per impostare password, accedere senza password e usare l’autenticazione a più fattori (MFA), in base al piano FoxIDs Cloud selezionato.

Configura le impostazioni MFA necessarie e le modalità di registrazione degli utenti; le importazioni descritte non trasferiscono le registrazioni MFA di Auth0. Per gli account con password, verifica i requisiti di lunghezza, complessità e scadenza: l’importazione di un hash non verifica i criteri durante l’importazione, ma i criteri selezionati si applicano all’accesso.

La configurazione delle applicazioni è un’attività separata dall’importazione degli utenti. Verifica emittente, destinatari, ambiti, claim e convalida dei token, oltre a presupposti dell’SDK Auth0, Actions, appartenenze a organizzazioni e assegnazioni di ruoli. Reimplementa il comportamento richiesto dall’applicazione. La guida generale alla migrazione descrive l’inventario complessivo delle applicazioni e le fasi di distribuzione.

Esportare un gruppo definito di utenti Auth0

Segui le istruzioni di Auth0 per l’esportazione in blocco degli utenti. Seleziona esplicitamente la connessione di origine con connection_id; un’esportazione API senza questo campo include tutte le connessioni. Mantieni distinguibili gli utenti del database, senza password e federati durante la conversione.

Usa un’esportazione compatibile con JSON (NDJSON) come origine della conversione. Le esportazioni CSV di Auth0 applicano escape aggiuntivi e non sono quindi input pronti per FoxIDs Seed Tool. Una piccola esportazione permette di provare la conversione nel formato CSV di Seed Tool.

Includi user_id, blocked e gli identificatori e gli stati di verifica usati da ogni connessione: email ed email_verified, oppure phone_number e phone_verified per gli utenti SMS. Per gli account social, aziendali e collegati, conserva provider, connessione e ID utente da identities per l’associazione degli account. Esporta solo i dati necessari dopo la migrazione e conserva tenant e connessione di origine insieme all’esportazione. Consulta lo schema del profilo utente Auth0 quando selezioni i campi.

Ottenere gli hash per mantenere le password

Richiedi l’esportazione degli hash delle password tramite Auth0 Support. È separata dall’esportazione dei dati utente. La guida di Auth0 all’esportazione degli hash descrive i record NDJSON e il campo passwordHash. L’esempio $2b$10$... identifica la variante bcrypt 2b e il costo 10.

Associa ogni hash all’utente corretto tramite tenant di origine, connessione al database e ID utente.

Mappare i dati utente e preservare gli account applicativi

FoxIDs crea un proprio ID utente persistente per gli utenti locali importati. Importare un user_id Auth0 come claim personalizzato non lo rende l’ID utente FoxIDs e non conserva automaticamente il claim sub dell’applicazione. Per gli accessi social e aziendali, verifica l’identità ricevuta direttamente dal provider e il soggetto emesso da FoxIDs all’applicazione.

Per mantenere l’ID utente Auth0 come sub dell’applicazione, importalo come claim personalizzato, ad esempio legacy_auth0_user_id. Nel metodo di autenticazione Login, configura una trasformazione di claim Map con azione Replace claim, claim di input legacy_auth0_user_id e claim di output sub. L’applicazione riceve così l’ID utente Auth0 come sub, mentre l’ID persistente FoxIDs dell’utente resta invariato.

Mantieni un’associazione tra identità di origine, nuova identità FoxIDs e account applicativo esistente. Ad esempio, durante la transizione l’identità Auth0 precedente e la nuova identità FoxIDs devono riferirsi allo stesso record cliente, senza crearne due. Verifica il soggetto effettivamente emesso per ogni applicazione e aggiorna l’associazione degli account dove necessario. Non collegare account solo perché gli indirizzi e-mail coincidono.

Per importare utenti locali, usa la seguente mappatura:

Migrare gli accessi social e aziendali

Crea un metodo di autenticazione FoxIDs per ogni connessione social o aziendale, stabilendo una relazione di fiducia diretta con il provider esterno. Gli utenti mantengono account e credenziali presso quel provider.

1. Identifica provider e configurazione di ogni connessione Auth0. Usa la guida di integrazione del provider pertinente, ad esempio Google, Facebook o Microsoft Entra ID, e seleziona il metodo supportato OpenID Connect, SAML 2.0 o WS-Federation.
2. Registra o configura FoxIDs presso il provider. Scambia le impostazioni client o i metadati di federazione e configura gli URL di callback e disconnessione indicati nella guida. Conserva la configurazione Auth0 durante la transizione.
3. Consenti il nuovo metodo di autenticazione nell’applicazione FoxIDs. Configura Home Realm Discovery affinché gli utenti possano selezionare il provider o esservi indirizzati dalle regole configurate.
4. Riconcilia l’identità del provider con l’account applicativo esistente. Gli identificatori restituiti durante un accesso di test possono essere confrontati con l’account di origine; un ID utente Auth0 non è necessariamente l’identificatore restituito direttamente a FoxIDs. Se devi conservare claim o assegnazioni di accesso per utente in FoxIDs, configura e provisiona utenti esterni.
5. Ricrea le restrizioni applicate in precedenza da Auth0, inclusi utenti bloccati e accesso alle organizzazioni.

Il flusso previsto è applicazione → FoxIDs → provider di identità esterno → FoxIDs → applicazione. FoxIDs emette i token dell’applicazione dopo che il provider ha autenticato l’utente.

Puoi provare ogni connessione avviando l’accesso dall’applicazione, selezionando il provider e completando il suo flusso. Puoi così osservare MFA, account e autorizzazioni nell’applicazione e comportamento di disconnessione.

Migrare gli utenti senza password

Importa gli utenti delle connessioni Auth0 senza password via e-mail o SMS come utenti interni FoxIDs senza password. Configura l’accesso senza password per mantenere l’accesso con codice monouso. Gli utenti che ricevevano un magic link Auth0 inseriscono invece un codice monouso nella pagina di accesso già aperta. Non devono quindi seguire link di accesso in e-mail o SMS.

1. Abilita e-mail o telefono come identificatore di accesso nel metodo FoxIDs Login e abilita Passwordless with email (one-time password) o Passwordless with SMS (one-time password) secondo necessità.
2. Per un metodo dedicato agli utenti senza password, seleziona Disable password authentication e disabilita impostazione/reimpostazione della password tramite e-mail e SMS. Il flusso resta così basato sui codici monouso.
3. Importa gli utenti omettendo Password e tutti i campi di hash della password. Mantieni SetPasswordEmail, SetPasswordSms e ChangePassword su false affinché non debbano scegliere una password. Preserva stato di verifica, stato di disabilitazione e claim necessari.

Per provare l’accesso senza password, puoi avviare l’accesso con l’e-mail o il telefono di un utente di test importato e inserire il codice ricevuto. Un codice valido consente a un utente abilitato di proseguire attraverso la MFA richiesta fino all’applicazione; codici non validi o scaduti e account disabilitati non concedono accesso.

Ad esempio, questo CSV di Seed Tool importa un utente fittizio con accesso senza password via e-mail:

Email;EmailVerified;SetPasswordEmail;SetPasswordSms;ChangePassword;DisableAccount
alice@example.com;true;false;false;false;false

Per gli utenti SMS, sostituisci Email ed EmailVerified con Phone e PhoneVerified, usando numero e stato di verifica esaminati. Si applica la stessa procedura di caricamento. L’utente resta senza password dopo un accesso senza password riuscito.

Importare utenti con hash delle password bcrypt

FoxIDs accetta stringhe bcrypt complete con prefissi $2a$, $2b$ o $2y$ e costi da 4 a 16. Per gli utenti con hash fuori dal formato supportato, usa l’impostazione della password via e-mail.

Abilita l’accesso via e-mail e l’autenticazione con password nel metodo FoxIDs Login per questi utenti.

Copia ogni valore Auth0 passwordHash associato nella colonna CSV PasswordHash e imposta PasswordHashAlgorithm su bcrypt. Preserva l’intera stringa, inclusi variante, costo e salt incorporato. È già codificata per bcrypt. Consulta i formati di hash delle password e il contratto di importazione password della Control API.

Per Seed Tool, usa le seguenti colonne. Questo è un account di test sintetico; sostituiscilo con l’esportazione verificata:

Email;EmailVerified;PasswordHashAlgorithm;PasswordHash;SetPasswordEmail;ChangePassword;DisableAccount
alice@example.com;true;bcrypt;$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC;false;false;false

Ometti Password e PasswordHashSalt. Mantieni SetPasswordEmail, SetPasswordSms e ChangePassword su false se l’utente deve continuare con la password esistente. Preserva stato di disabilitazione, verifica, claim e requisiti MFA dalla mappatura verificata. Includi PasswordLastChanged se conosci la data di modifica originale, in secondi Unix; altrimenti FoxIDs registra l’ora di importazione per i controlli sull’età della password.

La stessa procedura di caricamento si applica a tutte le importazioni di utenti locali. Il provisioning in blocco può sostituire un account esistente e le sue credenziali, indipendentemente dal formato della password scelto.

Con un utente di test importato puoi provare l’accesso con la password originale e ripeterlo con una errata. La password originale autentica l’utente in base ai criteri configurati e alla MFA; una password errata o un account disabilitato non concedono accesso. Puoi provare anche modifica e recupero della password dall’interfaccia Login configurata.

L’hash importato resta bcrypt dopo l’accesso. Una password impostata o modificata in FoxIDs viene salvata nel formato PBKDF2 predefinito. La cronologia continua a impedire il riutilizzo secondo i criteri scelti, anche quando un vecchio hash bcrypt viene conservato dopo la reimpostazione.

Importare utenti per l’impostazione della password

Usa questo metodo per account che sceglieranno una nuova password anziché importare un hash. Abilita accesso via e-mail, autenticazione con password e impostazione della password via e-mail nel metodo FoxIDs Login. Per gli utenti che devono restare senza password, segui Migrare gli utenti senza password.

L’importazione prepara gli account. L’impostazione della password avviene quando ogni utente avvia un accesso, non durante l’importazione.

Converti i record verificati in un file UTF-8 per FoxIDs Seed Tool. Le intestazioni distinguono maiuscole e minuscole e il separatore è il punto e virgola. L’esempio contiene utenti fittizi con e-mail precedentemente verificate; il secondo account resta disabilitato:

Email;EmailVerified;SetPasswordEmail;DisableAccount;RequireMultiFactor;Claims
alice@example.com;true;true;false;true;"[{""Claim"":""legacy_auth0_user_id"",""Values"":[""auth0|demo-001""]}]"
blocked@example.com;true;true;true;true;"[{""Claim"":""legacy_auth0_user_id"",""Values"":[""auth0|demo-002""]}]"

SetPasswordEmail=true seleziona l’impostazione della password con conferma via e-mail. Ometti Password e tutte le colonne di hash. Non servono una password temporanea condivisa o ChangePassword per questo flusso. RequireMultiFactor=true è il criterio scelto nell’esempio e richiede la configurazione dei metodi MFA corrispondenti.

Trasmetti il claim di esempio legacy_auth0_user_id solo alle applicazioni che ne hanno bisogno tramite la loro gestione configurata dei claim.

Caricare gli utenti ed esaminare il risultato

Usa questa procedura per utenti con hash bcrypt, utenti senza password e utenti che sceglieranno una password al primo accesso, con i campi adatti al metodo scelto.

Seed Tool divide i campi sui punti e virgola; i campi tra virgolette non possono contenere punti e virgola o interruzioni di riga. Usa le operazioni utente della Control API se i valori richiedono una rappresentazione d’importazione più ricca.

1. Scarica e configura Seed Tool per l’ambiente previsto. Imposta SeedSettings.UsersSvcPath sul file CSV convertito.
2. Esegui Seed Tool e seleziona U per caricare gli utenti in blocco.
3. Registra i nuovi ID utente nella mappatura di migrazione.

Puoi provare il caricamento con un CSV di pochi utenti in un ambiente di test. Seed Tool riporta il numero di operazioni riuscite e fallite. Puoi esaminare gli utenti importati in FoxIDs Control per vedere identificatori, stato di disabilitazione, claim e flag di impostazione della password.

Seed Tool usa il provisioning in blocco, che può sostituire gli utenti esistenti invece di unirli in modo sicuro. Controlla le collisioni prima del caricamento. Non rieseguire l’intero file dopo che gli utenti hanno impostato password o ottenuto accesso: la sostituzione può rimuovere credenziali e stato e creare nuovi ID. Riconcilia un’importazione parziale prima di riprovare; gestisci le modifiche successive con aggiornamenti utente mirati e verificati.

Impostazione della password al primo accesso

Per un utente importato abilitato con SetPasswordEmail=true, il flusso previsto è:

1. L’utente apre l’applicazione e avvia l’accesso tramite FoxIDs Login.
2. FoxIDs identifica l’utente dall’indirizzo e-mail e invia un codice di conferma.
3. L’utente invia il codice e una nuova password conforme ai criteri FoxIDs.
4. FoxIDs verifica l’e-mail, salva la password e azzera i flag di impostazione. L’accesso prosegue attraverso gli eventuali passaggi MFA richiesti prima di tornare all’applicazione.

Importare un utente non invia l’e-mail di impostazione. Gli accessi successivi usano la nuova password FoxIDs, non quella precedente di Auth0. Se un utente non può ricevere il codice, usa una procedura di recupero approvata che ne verifichi l’identità.

Puoi esplorare il flusso con un utente di test seguendo i passaggi precedenti. Questi scenari mostrano i risultati previsti:

Distribuire e mantenere un percorso di rollback

La migrazione può essere distribuita per applicazione o gruppo di utenti. Gli utenti possono continuare tramite l’URL abituale con il flusso configurato: password esistente, impostazione della password, codice monouso o provider esterno esistente.

Prima di ogni importazione in produzione, riconcilia gli utenti creati, modificati, bloccati o eliminati dopo l’esportazione. Definisci un breve blocco delle modifiche o un altro processo controllato di riconciliazione. Non sovrascrivere utenti già migrati per applicare questi cambiamenti.

Monitora consegna di e-mail e SMS, errori di impostazione della password, accessi falliti e problemi di associazione degli account. Per gli import di hash, considera le modifiche delle password in Auth0 successive all’esportazione, evitando che gli utenti arrivino con una password diversa dall’hash importato. Il rollback richiede che la precedente configurazione Auth0 resti disponibile. Puoi provare a ripristinarla per un’applicazione di test e osservare il ritorno al flusso Auth0.

Una password impostata in FoxIDs non viene sincronizzata nuovamente in Auth0. Il rollback usa quindi le credenziali ancora conservate in Auth0. Definisci come gli utenti creati solo in FoxIDs accederanno tramite Auth0 se serve un rollback. Per gli accessi senza password e federati, conserva impostazioni di consegna e connessioni ai provider Auth0 necessarie a ripristinare il flusso precedente. Ritira la vecchia integrazione ed elimina i file esportati conservati solo dopo l’accettazione dell’accesso agli account e del supporto operativo.

Documentazione correlata

• Panoramica della migrazione
• Caricare molti utenti
• Operazioni utente della Control API
• Accesso e Home Realm Discovery
• Provider e-mail
• Applicazioni