Migrar de Auth0 a FoxIDs

Traslada los inicios de sesión de Auth0 a FoxIDs con el enfoque de migración adecuado para cada conexión. Importa usuarios de bases de datos con hashes de contraseña bcrypt o permite que elijan una contraseña nueva. Importa los usuarios sin contraseña y activa los códigos de un solo uso. Para los inicios de sesión sociales y empresariales, configura métodos de autenticación de FoxIDs que confíen en los proveedores de identidad externos.

Esta guía técnica aborda la configuración de aplicaciones, la importación de usuarios y la correspondencia de cuentas para conexiones de Auth0 de base de datos, sin contraseña por correo/SMS, sociales y empresariales.

Para usuarios de bases de datos y sin contraseña, convierte la exportación de Auth0 revisada en un archivo CSV y utiliza FoxIDs Seed Tool para cargar los usuarios en masa en FoxIDs. Los ejemplos CSV siguientes muestran los campos de cada enfoque de migración.

Elige un método para cada grupo antes de preparar la importación:

Los usuarios importados con contraseña y sin ella se autentican localmente en FoxIDs. Los usuarios sociales y empresariales se autentican en el proveedor de identidad conectado.

Preparar el destino y la aplicación

Un entorno de pruebas dedicado permite probar la migración con un grupo pequeño de usuarios antes de pasar a producción. Los pasos de configuración son:

1. Si quieres un dominio personalizado, configúralo y verifícalo en el inquilino antes de configurar aplicaciones y proveedores de identidad externos. Utiliza las URL de FoxIDs resultantes durante toda la migración. Cambiar el dominio más adelante requiere actualizar las configuraciones externas, incluidas las URL de autoridad o metadatos de las aplicaciones y las URL de devolución de llamada y cierre de sesión de los proveedores.
2. Cada entorno tiene un método de autenticación Login predeterminado llamado login. Personaliza su imagen de marca e interfaz de inicio de sesión para conseguir el aspecto deseado y ajusta sus opciones de inicio de sesión a los usuarios importados.
3. Crea los métodos de autenticación que conecten a los usuarios sociales y empresariales con sus proveedores de identidad externos siguiendo la sección de migración correspondiente.
4. Configura la aplicación, sus URL de redirección permitidas, el comportamiento del cierre de sesión y las API que acepten sus tokens de acceso.

FoxIDs Cloud proporciona envío de correo electrónico y SMS para crear contraseñas, iniciar sesión sin contraseña y realizar autenticación multifactor (MFA), según el plan de FoxIDs Cloud seleccionado.

Configura los ajustes de MFA necesarios y cómo se inscribirán los usuarios; las importaciones descritas aquí no transfieren los registros de MFA de Auth0. Para cuentas con contraseña, revisa los requisitos de longitud, complejidad y caducidad: importar un hash omite la validación de la política durante la importación, pero la política seleccionada se aplica al iniciar sesión.

La configuración de aplicaciones es un trabajo separado de la importación de usuarios. Revisa emisor, audiencia, ámbitos, reclamaciones y validación de tokens, además de las suposiciones del SDK de Auth0, Actions, pertenencia a organizaciones y asignaciones de roles. Reimplementa el comportamiento que necesita la aplicación. La guía general de migración aborda el inventario más amplio de aplicaciones y los pasos de despliegue.

Exportar un grupo definido de usuarios de Auth0

Sigue las instrucciones de exportación masiva de usuarios de Auth0. Selecciona explícitamente la conexión de origen con connection_id; una exportación API sin este campo incluye todas las conexiones. Mantén diferenciados los usuarios de bases de datos, sin contraseña y federados durante la conversión.

Utiliza una exportación compatible con JSON (NDJSON) como origen de la conversión. Las exportaciones CSV de Auth0 aplican escapes adicionales, por lo que no son entradas listas para FoxIDs Seed Tool. Una exportación pequeña permite probar la conversión al formato CSV de Seed Tool.

Incluye user_id, blocked y los identificadores y estados de verificación utilizados por cada conexión: email y email_verified, o phone_number y phone_verified para usuarios de SMS. Para cuentas sociales, empresariales y vinculadas, conserva el proveedor, la conexión y el ID de usuario de identities para la correspondencia de cuentas. Exporta solo los datos necesarios tras la migración y conserva el inquilino y la conexión de origen junto a la exportación. Consulta el esquema del perfil de usuario de Auth0 al seleccionar campos.

Obtener hashes para conservar las contraseñas

Solicita la exportación de hashes de contraseña a Auth0 Support. Es independiente de la exportación de datos de usuario. La guía de exportación de hashes de Auth0 describe los registros NDJSON y el campo passwordHash. Su ejemplo $2b$10$... identifica la variante bcrypt 2b y el coste 10.

Asocia cada hash al usuario correcto mediante el inquilino de origen, la conexión de base de datos y el ID de usuario.

Asignar datos de usuario y conservar las cuentas de las aplicaciones

FoxIDs crea su propio ID de usuario persistente para los usuarios locales importados. Importar un user_id de Auth0 como reclamación personalizada no lo convierte en el ID de usuario de FoxIDs ni conserva automáticamente la reclamación sub de la aplicación. Para inicios de sesión sociales y empresariales, comprueba la identidad recibida directamente del proveedor y el sujeto que FoxIDs emite a la aplicación.

Para conservar el ID de usuario de Auth0 como sub de la aplicación, impórtalo como reclamación personalizada, por ejemplo legacy_auth0_user_id. En el método de autenticación Login, configura una transformación de reclamaciones Map con la acción Replace claim, la reclamación de entrada legacy_auth0_user_id y la de salida sub. La aplicación recibe entonces el ID de usuario de Auth0 como sub, mientras que el ID persistente de FoxIDs no cambia.

Mantén una correspondencia entre la identidad de origen, la nueva identidad de FoxIDs y la cuenta existente de la aplicación. Por ejemplo, durante la transición, la identidad antigua de Auth0 y la nueva de FoxIDs deben apuntar al mismo registro de cliente, sin crear dos registros. Comprueba el sujeto real emitido a cada aplicación y actualiza su correspondencia de cuentas cuando sea necesario. No vincules cuentas solo porque sus direcciones de correo coincidan.

Para importar usuarios locales, utiliza la siguiente correspondencia:

Migrar los inicios de sesión sociales y empresariales

Crea un método de autenticación de FoxIDs para cada conexión social o empresarial que establezca confianza directamente con el proveedor de identidad externo. Los usuarios conservan sus cuentas y credenciales en ese proveedor.

1. Identifica el proveedor y la configuración de cada conexión de Auth0. Utiliza la guía de integración del proveedor correspondiente, como Google, Facebook o Microsoft Entra ID, y selecciona el método compatible de OpenID Connect, SAML 2.0 o WS-Federation.
2. Registra o configura FoxIDs en el proveedor. Intercambia los ajustes del cliente o los metadatos de federación y configura las URL de devolución de llamada y cierre de sesión indicadas en la guía. Conserva la configuración de Auth0 durante la transición.
3. Permite el nuevo método de autenticación en la aplicación de FoxIDs. Configura Home Realm Discovery para que los usuarios puedan seleccionar su proveedor o ser dirigidos a él mediante las reglas configuradas.
4. Concilia la identidad del proveedor con la cuenta existente de la aplicación. Los identificadores devueltos en un inicio de sesión de prueba pueden compararse con la cuenta de origen; un ID de usuario de Auth0 no es necesariamente el identificador devuelto directamente a FoxIDs. Si necesitas almacenar reclamaciones o asignaciones de acceso por usuario en FoxIDs, configura y aprovisiona usuarios externos.
5. Recrea las restricciones que antes aplicaba Auth0, incluidos los usuarios bloqueados y el acceso a organizaciones.

El flujo esperado es aplicación → FoxIDs → proveedor de identidad externo → FoxIDs → aplicación. FoxIDs emite los tokens de la aplicación después de que el proveedor autentique al usuario.

Puedes probar cada conexión iniciando sesión desde la aplicación, seleccionando el proveedor y completando su flujo de inicio de sesión. Esto permite observar la MFA, la cuenta y los permisos en la aplicación y el comportamiento del cierre de sesión.

Migrar usuarios sin contraseña

Importa usuarios de las conexiones sin contraseña por correo o SMS de Auth0 como usuarios internos de FoxIDs sin contraseña. Configura el inicio de sesión sin contraseña para que sigan accediendo con un código de un solo uso. Los usuarios que antes recibían un enlace mágico de Auth0 introducen en su lugar un código en la página de inicio de sesión ya abierta. Así no tienen que seguir enlaces de inicio de sesión en correos o SMS.

1. Activa el correo o teléfono como identificador de inicio de sesión en el método de autenticación FoxIDs Login y habilita Passwordless with email (one-time password) o Passwordless with SMS (one-time password) según corresponda.
2. Para un método de inicio de sesión dedicado a usuarios sin contraseña, selecciona Disable password authentication y desactiva la creación/restablecimiento de contraseña por correo y SMS. Así el flujo se centra en los códigos de un solo uso.
3. Importa los usuarios omitiendo Password y todos los campos de hash de contraseña. Mantén SetPasswordEmail, SetPasswordSms y ChangePassword en false para que no tengan que elegir una contraseña. Conserva los estados de verificación y deshabilitación y las reclamaciones necesarias.

Para probar el inicio de sesión sin contraseña, puedes iniciarlo con el correo o teléfono de un usuario de prueba importado e introducir el código recibido. Un código válido permite a un usuario habilitado continuar a través de la MFA requerida hasta la aplicación; los códigos no válidos o caducados y las cuentas deshabilitadas no dan acceso.

Por ejemplo, este CSV de Seed Tool importa un usuario ficticio sin contraseña por correo:

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

Para usuarios de SMS, sustituye Email y EmailVerified por Phone y PhoneVerified, con el teléfono y estado de verificación revisados. Se aplica el mismo procedimiento de carga. Tras un inicio de sesión sin contraseña correcto, el usuario sigue sin contraseña.

Importar usuarios con hashes de contraseña bcrypt

FoxIDs acepta cadenas bcrypt completas con prefijos $2a$, $2b$ o $2y$ y costes de 4 a 16. Para usuarios cuyos hashes estén fuera del formato compatible, utiliza la creación de contraseña por correo.

Activa el inicio de sesión por correo y la autenticación con contraseña en el método de autenticación FoxIDs Login para estos usuarios.

Copia cada valor Auth0 passwordHash asociado en la columna CSV PasswordHash y establece PasswordHashAlgorithm en bcrypt. Conserva la cadena completa, incluida su variante, coste y sal integrada. Ya está codificada para bcrypt. Consulta los formatos de hash de contraseña y el contrato de importación de contraseñas de Control API.

Para Seed Tool, utiliza las siguientes columnas. Esta es una cuenta de prueba sintética; sustitúyela por tu exportación revisada:

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

Omite Password y PasswordHashSalt. Mantén SetPasswordEmail, SetPasswordSms y ChangePassword en false si el usuario debe continuar con su contraseña existente. Conserva los estados de deshabilitación y verificación, las reclamaciones y los requisitos de MFA de la correspondencia revisada. Incluye PasswordLastChanged si conoces la fecha de cambio original, en segundos Unix; de lo contrario, FoxIDs registra la fecha de importación para comprobar la antigüedad de la contraseña.

El mismo procedimiento de carga se aplica a todas las importaciones de usuarios locales. El aprovisionamiento masivo puede sustituir una cuenta existente y sus credenciales, independientemente del formato de contraseña elegido.

Con un usuario de prueba importado, puedes probar el inicio de sesión con la contraseña original y repetirlo con una incorrecta. La contraseña original autentica al usuario según la política de contraseñas configurada y la MFA; una contraseña incorrecta o una cuenta deshabilitada no concede acceso. También puedes probar el cambio y la recuperación de contraseña mediante la interfaz Login configurada.

El hash importado sigue siendo bcrypt después del inicio de sesión. Una contraseña establecida o modificada en FoxIDs se almacena con el formato PBKDF2 predeterminado de FoxIDs. El historial sigue impidiendo la reutilización según la política seleccionada, incluso si se conserva un hash bcrypt antiguo tras restablecer una contraseña.

Importar usuarios para crear una contraseña

Utiliza este método para cuentas que elegirán una contraseña nueva en lugar de importar un hash. Activa el inicio de sesión por correo, la autenticación con contraseña y la creación de contraseña por correo en el método de autenticación FoxIDs Login. Para usuarios que deben seguir sin contraseña, consulta Migrar usuarios sin contraseña.

La importación prepara las cuentas. La contraseña se crea cuando cada usuario inicia sesión, no durante la importación.

Convierte los registros revisados en un archivo UTF-8 para FoxIDs Seed Tool. Los encabezados distinguen mayúsculas y minúsculas y el separador es un punto y coma. Este ejemplo contiene usuarios ficticios con direcciones de correo verificadas anteriormente; la segunda cuenta permanece deshabilitada:

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 selecciona la creación de contraseña con confirmación por correo. Omite Password y todas las columnas de hash. No necesitas una contraseña temporal compartida ni ChangePassword para este flujo. RequireMultiFactor=true es la política elegida en el ejemplo y requiere configurar los métodos de MFA correspondientes.

Entrega la reclamación de ejemplo legacy_auth0_user_id solo a las aplicaciones que la necesiten, mediante su tratamiento configurado de reclamaciones.

Cargar usuarios y examinar el resultado

Utiliza este procedimiento para usuarios con hashes bcrypt, usuarios sin contraseña y usuarios que elegirán una contraseña en el primer inicio de sesión, con los campos adecuados al método seleccionado.

Seed Tool divide los campos por puntos y coma; los campos entre comillas no pueden contener puntos y coma ni saltos de línea. Utiliza las operaciones de usuarios de Control API si tus valores necesitan una representación de importación más completa.

1. Descarga y configura Seed Tool para el entorno previsto. Establece SeedSettings.UsersSvcPath en el archivo CSV convertido.
2. Ejecuta Seed Tool y selecciona U para cargar los usuarios en masa.
3. Registra los nuevos ID de usuario en la correspondencia de migración.

Puedes probar la carga con un CSV de pocos usuarios en un entorno de pruebas. Seed Tool informa de los recuentos de éxitos y errores. En FoxIDs Control puedes examinar los identificadores, estado de deshabilitación, reclamaciones e indicadores de creación de contraseña de los usuarios importados.

Seed Tool utiliza aprovisionamiento masivo, que puede sustituir usuarios existentes en lugar de fusionarlos de forma segura. Comprueba las colisiones antes de cargar. No vuelvas a ejecutar el archivo completo después de que los usuarios establezcan contraseñas u obtengan acceso: la sustitución puede eliminar credenciales y estado y crear nuevos ID de usuario. Concilia una importación parcial antes de reintentar; gestiona los cambios posteriores mediante actualizaciones de usuario revisadas y específicas.

Crear la contraseña en el primer inicio de sesión

Para un usuario importado habilitado con SetPasswordEmail=true, el flujo esperado es:

1. El usuario abre la aplicación e inicia sesión mediante FoxIDs Login.
2. FoxIDs identifica al usuario por su dirección de correo y envía un código de confirmación.
3. El usuario envía el código y una contraseña nueva que cumple la política de FoxIDs.
4. FoxIDs verifica la dirección de correo, guarda la contraseña y borra los indicadores de creación de contraseña. El inicio de sesión continúa por los pasos de MFA requeridos antes de volver a la aplicación.

Importar un usuario no envía el correo de creación de contraseña. Los inicios de sesión posteriores utilizan la nueva contraseña de FoxIDs, no la anterior de Auth0. Si un usuario no puede recibir el código, utiliza un proceso de recuperación aprobado que verifique su identidad.

Puedes explorar el flujo con un usuario de prueba siguiendo los pasos anteriores. Estos escenarios muestran los resultados esperados:

Desplegar y conservar una vía de reversión

La migración puede desplegarse por aplicación o grupo de usuarios. Los usuarios pueden seguir usando su URL habitual con el flujo configurado: contraseña existente, creación de contraseña, código de un solo uso o proveedor de identidad externo actual.

Antes de cada importación de producción, concilia los usuarios creados, modificados, bloqueados o eliminados desde la exportación. Define una breve congelación de cambios u otro proceso controlado de conciliación. No sobrescribas usuarios ya migrados para aplicar estos cambios.

Supervisa la entrega de correo y SMS, los errores de creación de contraseña, los fallos de inicio de sesión y los problemas de correspondencia de cuentas. En las importaciones de hashes, ten en cuenta los cambios de contraseña en Auth0 posteriores a la exportación para que los usuarios no lleguen con una contraseña distinta del hash importado. La reversión depende de que siga disponible la configuración anterior de Auth0. Puedes probar a restaurarla para una aplicación de prueba y observar el regreso al flujo de Auth0.

Una contraseña establecida en FoxIDs no se sincroniza de vuelta a Auth0. Por tanto, una reversión utiliza las credenciales que todavía conserva Auth0. Define cómo accederán mediante Auth0 los usuarios creados solo en FoxIDs si es necesario revertir. Para los inicios de sesión sin contraseña y federados, conserva los ajustes de entrega y conexiones a proveedores de Auth0 necesarios para recuperar el flujo anterior. Retira la integración antigua y elimina los archivos exportados conservados solo después de aceptar el acceso a las cuentas y el soporte operativo.

Documentación relacionada

• Visión general de la migración
• Cargar muchos usuarios
• Operaciones de usuarios de Control API
• Inicio de sesión y Home Realm Discovery
• Proveedor de correo electrónico
• Aplicaciones