Migración de usuarios a Azure AD B2C: Guía técnica desde GitHub

Introducción

Migrar usuarios desde un proveedor de identidad heredado hacia Azure AD B2C no consiste únicamente en copiar registros de una base de datos. El punto crítico suele estar en las credenciales: en muchos escenarios no es posible importar directamente contraseñas existentes, especialmente si solo se dispone de hashes generados con algoritmos o políticas propias del sistema original.

El repositorio oficial azure-ad-b2c/user-migration proporciona ejemplos de User Journeys para realizar migraciones desde proveedores de identidad heredados hacia Azure AD B2C. Su enfoque es especialmente útil cuando se quiere diseñar una migración progresiva, en la que los usuarios se incorporan al nuevo directorio a medida que inician sesión.

Este artículo resume los patrones técnicos más relevantes, las decisiones de arquitectura y las precauciones que conviene tener presentes antes de llevar una migración de identidades a producción.

Qué aporta el repositorio `azure-ad-b2c/user-migration`

El repositorio no debe entenderse como una herramienta universal de migración lista para ejecutar en cualquier entorno. Su valor está en mostrar patrones de implementación para Azure AD B2C mediante custom policies y recorridos de usuario personalizados.

En términos prácticos, los ejemplos ayudan a resolver preguntas como:

Cómo detectar si un usuario ya ha sido migrado.
Cómo delegar temporalmente la validación de credenciales en un sistema heredado.
Cómo actualizar el estado del usuario en Azure AD B2C después de una autenticación correcta.
Cómo separar la experiencia de inicio de sesión del proceso técnico de migración.
Cómo integrar llamadas REST dentro de un recorrido de usuario cuando se necesita consultar un sistema externo.

La idea central es evitar una migración masiva insegura de contraseñas y favorecer un modelo controlado, auditable y gradual.

Estrategias habituales de migración

Antes de elegir una implementación, conviene distinguir entre varios enfoques.

1. Migración con restablecimiento de contraseña

En este modelo se crean los usuarios en Azure AD B2C sin conservar la contraseña original. Después, cada usuario debe establecer una nueva contraseña mediante un flujo de restablecimiento o una experiencia equivalente.

Es un patrón sencillo desde el punto de vista técnico, pero puede tener impacto en la experiencia de usuario.

Ventajas:

Reduce la dependencia del sistema heredado.
Evita manipular contraseñas o hashes heredados.
Simplifica la retirada del proveedor anterior.

Inconvenientes:

Obliga al usuario a realizar una acción adicional.
Puede aumentar el volumen de soporte durante el cambio.
Requiere una comunicación clara con los usuarios.

2. Migración progresiva o just-in-time

En este modelo, el usuario se migra cuando inicia sesión por primera vez en la nueva plataforma. Azure AD B2C puede apoyarse en una llamada a un sistema heredado para validar las credenciales. Si la validación es correcta, el usuario queda actualizado o creado en Azure AD B2C y el sistema marca que la migración ya se ha completado.

Este es el tipo de patrón que encaja con los ejemplos del repositorio oficial.

Ventajas:

Mejora la experiencia de usuario frente a un restablecimiento masivo.
Permite migrar de forma gradual.
Reduce el riesgo operativo de una migración completa en una única ventana.

Inconvenientes:

Requiere mantener disponible el sistema heredado durante el periodo de transición.
Añade complejidad a las custom policies.
Exige un diseño cuidadoso del servicio REST intermedio y de los controles de seguridad.

3. Migración administrativa previa

En algunos escenarios se puede crear previamente la cuenta de los usuarios en Azure AD B2C, pero no necesariamente su contraseña real. Después, el primer inicio de sesión, una validación externa o un restablecimiento controlado completan el proceso.

Este enfoque puede ser útil cuando se necesita preparar atributos de perfil, segmentaciones o integraciones antes de abrir el acceso a los usuarios finales.

Consideraciones importantes sobre contraseñas

Una decisión frecuente, pero peligrosa, es intentar “migrar contraseñas” copiando hashes desde el sistema anterior. En general, este enfoque no es portable entre proveedores de identidad, porque cada plataforma puede usar algoritmos, sales, formatos de almacenamiento y políticas de validación diferentes.

Para una migración hacia Azure AD B2C, las opciones más realistas suelen ser:

pedir al usuario que defina una nueva contraseña;
validar la contraseña una vez contra el sistema heredado y, si es correcta, establecer una nueva credencial en Azure AD B2C;
usar federación temporal con el proveedor anterior si el escenario lo permite;
mantener un proceso controlado de transición hasta retirar el sistema legado.

La migración progresiva evita exponer o transformar hashes de contraseña y permite validar al usuario contra el sistema que todavía conoce su credencial original.

Arquitectura de referencia para una migración progresiva

Un diseño típico basado en los patrones del repositorio puede tener los siguientes componentes:

Azure AD B2C
Ejecuta el recorrido de usuario personalizado y mantiene el estado final de la identidad.
Custom policy / User Journey
Define la lógica de autenticación, comprobación de estado y llamadas a servicios externos.
Servicio REST de migración
Expone una API segura que Azure AD B2C puede invocar durante el recorrido. Este servicio valida credenciales contra el sistema heredado o consulta el estado de migración.
Proveedor de identidad o repositorio heredado
Sistema donde residen los usuarios antes de completar la migración.
Atributo de estado de migración
Marca si un usuario ya ha sido migrado, si requiere validación externa o si debe seguir otro camino dentro del flujo.

El flujo conceptual sería:

Usuario inicia sesión
        |
        v
Azure AD B2C ejecuta el User Journey
        |
        v
¿Usuario ya migrado?
   |             |
   | sí          | no
   v             v
Autenticación    Llamada REST al sistema heredado
normal           |
                 v
          ¿Credenciales válidas?
             |             |
             | sí          | no
             v             v
      Actualizar usuario   Rechazar inicio de sesión
      y marcar migrado

Este diagrama es intencionadamente conceptual. La implementación concreta depende de los atributos disponibles, del sistema de origen, de la política de contraseñas y de la experiencia de usuario que se quiera ofrecer.

Diseño del servicio REST de migración

El servicio REST es una pieza crítica. No debería ser una API genérica expuesta sin restricciones, sino un componente específico para el proceso de migración.

Entre sus responsabilidades habituales pueden estar:

recibir el identificador del usuario y, si procede, la contraseña introducida;
validar esas credenciales contra el sistema heredado;
devolver a Azure AD B2C una respuesta mínima y estructurada;
registrar eventos de auditoría sin almacenar secretos;
aplicar controles de tasa, bloqueo y protección frente a abuso;
evitar revelar si una cuenta existe o no cuando eso pueda facilitar enumeración de usuarios.

Un contrato simplificado podría tener esta forma:

{
  "signInName": "[email protected]",
  "password": "valor_introducido_por_el_usuario"
}

Y una respuesta mínima:

{
  "migrationRequired": true,
  "legacyCredentialsValid": true
}

Este ejemplo es ilustrativo. En producción, el contrato debe alinearse con las claims utilizadas por la custom policy, la semántica del sistema heredado y los requisitos de seguridad de la organización.

Creación o actualización de usuarios en Azure AD B2C

En una migración se pueden crear usuarios de forma previa o durante el flujo, según la estrategia elegida. Cuando se usan cuentas locales en Azure AD B2C, la identidad de inicio de sesión se representa mediante atributos específicos del usuario, y no basta con copiar un username de una tabla heredada.

Un ejemplo orientativo de creación de usuario local mediante Microsoft Graph tendría esta estructura general:

{
  "accountEnabled": true,
  "displayName": "Ana García",
  "identities": [
    {
      "signInType": "emailAddress",
      "issuer": "contoso.onmicrosoft.com",
      "issuerAssignedId": "[email protected]"
    }
  ],
  "passwordProfile": {
    "password": "ContraseñaInicialTemporal!",
    "forceChangePasswordNextSignIn": false
  },
  "passwordPolicies": "DisablePasswordExpiration"
}

Aspectos a tener en cuenta:

El valor de issuer debe corresponder al dominio del tenant.
La contraseña inicial debe cumplir la política aplicable.
No conviene reutilizar contraseñas procedentes del sistema heredado.
En escenarios B2C, el cambio forzado de contraseña en el siguiente inicio de sesión no debe asumirse sin validar el comportamiento exacto del flujo elegido.
Los atributos personalizados, si se usan, deben estar definidos previamente y tratados de forma coherente por las policies.

La parte más importante no es el JSON en sí, sino el modelo de estado: la aplicación y las policies deben saber si el usuario está pendiente de migración, migrado o requiere una acción adicional.

Atributos de estado de migración

Un patrón habitual consiste en añadir un atributo que indique el estado de migración del usuario. Por ejemplo:

migrationRequired
isMigrated
legacyUserId
migrationStatus

El nombre exacto dependerá de la implementación, pero la función es la misma: permitir que el recorrido de usuario tome decisiones.

Ejemplo conceptual:

migrationRequired = true

Cuando el usuario introduce sus credenciales, Azure AD B2C puede invocar el servicio REST de migración. Si el sistema heredado confirma que las credenciales son válidas, la policy actualiza el usuario y cambia el estado:

migrationRequired = false

A partir de ese momento, el usuario debería autenticarse directamente contra Azure AD B2C, sin depender del proveedor anterior.

Seguridad durante la migración

La migración de identidades es una operación sensible. Algunas recomendaciones prácticas:

No exportar contraseñas en texto claro.
Evitar almacenar hashes heredados salvo que exista una justificación técnica y legal clara.
Cifrar cualquier fichero temporal que contenga datos personales.
Limitar el acceso al servicio REST de migración.
Registrar auditoría sin incluir contraseñas, tokens ni secretos.
Usar secretos gestionados y rotación de credenciales para las integraciones.
Aplicar controles de bloqueo, límites de intentos y detección de abuso.
Probar el comportamiento ante usuarios inexistentes, bloqueados o duplicados.
Definir un plan de retirada del sistema heredado.
Documentar cómo se gestionarán incidencias durante el periodo de convivencia.

También conviene separar claramente los entornos de desarrollo, pruebas y producción. Las custom policies deben probarse con usuarios de prueba antes de ejecutarse sobre cuentas reales.

Pruebas recomendadas antes de producción

Antes de activar una migración progresiva para usuarios reales, es recomendable validar al menos estos casos:

Caso	Resultado esperado
Usuario ya migrado	Inicia sesión directamente en Azure AD B2C
Usuario no migrado con contraseña válida	Se valida contra el sistema heredado y queda migrado
Usuario no migrado con contraseña incorrecta	Se rechaza el inicio de sesión sin migrarlo
Usuario inexistente	Se devuelve un error controlado
Usuario bloqueado en el sistema heredado	No se completa la migración
Servicio REST no disponible	El flujo falla de forma controlada
Atributos incompletos	No se crea ni actualiza una identidad inconsistente
Usuario duplicado	Se aplica una regla de resolución definida previamente

Estas pruebas deben combinar validación funcional, seguridad, rendimiento y observabilidad.

Errores comunes

Algunos problemas frecuentes en proyectos de migración a Azure AD B2C son:

Asumir que los hashes de contraseña se pueden importar sin cambios.
Diseñar el servicio REST como una API pública sin controles suficientes.
No diferenciar entre usuario pendiente de migración y usuario ya migrado.
No contemplar usuarios duplicados o correos electrónicos no verificados.
Exponer mensajes de error que permiten enumerar cuentas.
Mantener indefinidamente la dependencia del sistema heredado.
No probar los flujos de error de las custom policies.
Tratar la migración como una tarea puramente técnica y no como un cambio operativo.

Checklist técnico

Antes de iniciar la migración, conviene revisar:

Conclusión

El repositorio azure-ad-b2c/user-migration es una referencia útil para diseñar migraciones progresivas hacia Azure AD B2C mediante User Journeys y custom policies. Su principal aportación no es automatizar toda la migración, sino mostrar cómo integrar Azure AD B2C con un sistema heredado durante el proceso de autenticación.

La clave técnica está en tratar la migración como un flujo de identidad controlado: validar al usuario, actualizar su estado, reducir la exposición de credenciales y retirar gradualmente la dependencia del proveedor anterior. Con una arquitectura bien diseñada, pruebas suficientes y controles de seguridad adecuados, este patrón permite migrar usuarios sin imponer necesariamente un restablecimiento masivo de contraseñas desde el primer día.

Fuente

azure-ad-b2c/user-migration en GitHub