Personaliza la inscripción en MFA en Universal Login

Personaliza los flujos de MFA mediante Actions de post-login para solicitar a los usuarios que se inscriban en factores específicos.

Auth0 admite varios factores para proteger el acceso de los usuarios con autenticación multifactor (MFA). Mediante Actions post-login, puedes personalizar tus flujos de MFA para solicitar a los usuarios que se inscriban en factores específicos. Después de que un usuario se inscriba en un factor, podrá usarlo como método secundario de autenticación en futuros inicios de sesión.

También puedes usar información contextual para personalizar aún más tus flujos de inscripción en MFA. Por ejemplo, puedes solicitar a los usuarios que se inscriban en SMS para una aplicación, mientras que para otra puedes pedirles que se inscriban en notificaciones push o en WebAuthn.

Esta función te permite personalizar tus flujos de inscripción en MFA. Si quieres personalizar los flujos de MFA para usuarios que ya están inscritos, consulta Personalizar la selección de MFA para Universal Login.

​

Cómo funciona

Puedes usar Actions para personalizar tus flujos de inscripción en MFA. En concreto, puedes modificar el trigger post-login de Login Flow con los siguientes métodos de Authentication API:

• enrollWith: Especifica el factor predeterminado que se presenta a los usuarios durante la inscripción. Opcionalmente, puedes proporcionar una lista alternativa de factores para que los usuarios elijan. Si la proporcionas, se muestra un enlace Probar otro método en la pantalla de inscripción.

• enrollWithAny: Especifica un conjunto de factores entre los que los usuarios pueden elegir durante la inscripción. De forma predeterminada, este método muestra una pantalla de selección que permite a los usuarios elegir el factor que prefieran. En algunos casos, la experiencia del usuario puede variar:

  • Si se han especificado dos o más factores, se muestra la pantalla de selección al usuario.
  • Si el usuario ya se ha inscrito en todos los factores especificados excepto en uno, se omite la pantalla de selección y se le solicita que se inscriba en el factor restante.
  • Si el usuario ya se ha inscrito en todos los factores especificados, el comando falla y la secuencia de inicio de sesión continúa.

Puedes usar una combinación de estos métodos para personalizar tus flujos de inscripción en MFA. También puedes incorporar metadatos del usuario, como roles o la fecha del último inicio de sesión, para crear experiencias más personalizadas.

Los flujos de inscripción personalizados admiten los siguientes factores:

• otp

• recovery-code

• push-notification

• phone

  • preferredMethod: voice
  • preferredMethod: sms
  • preferredMethod: both

• webauthn-platform

• webauthn-roaming

Después de que un usuario se inscriba en un factor, su valor se agrega a enrolledFactors. Esta propiedad representa la lista de factores activos asociados a su cuenta de usuario.

El array event.authentication.methods incluye un campo type cuando el nombre del método es mfa. Este campo contiene valores de factor (string) que coinciden con los que usa el campo type de enrolledFactors.

Cuando se produce una inscripción en MFA, methods contiene el objeto name:mfa con type establecido en el factor usado para ese evento. methods y enrolledFactors solo se actualizan al inicio de una Action. Puedes acceder a los resultados de un evento de inscripción en la siguiente Action del flujo.

Para obtener más información, consulta los siguientes recursos:

• Actions Triggers: post-login - Event Object
• Actions Triggers: post-login - API Object

​

Flujos secuenciados y contextuales

Con los comandos enrollWith o enrollWithAny, puedes usar información contextual para determinar la mejor opción de inscripción o la mejor serie de inscripciones para mostrar a los usuarios.

• El comando enrollWith admite un factor inicial o predeterminado y una lista de alternativas. Los usuarios solo pueden inscribirse en un factor por comando.
• El comando enrollWithAny admite una lista de factores. El orden especificado de los factores determina cómo se muestra la lista a los usuarios. Los usuarios solo pueden inscribirse en un factor por comando.

Con estos comandos, puedes aprovechar lo siguiente:

• Flujos secuenciados: Inscribe a los usuarios en una serie de factores en un orden específico.
• Flujos contextuales: Determina qué factor mostrar al usuario en función de los metadatos o de comandos anteriores en el flujo.

Para ilustrar mejor estos flujos, considera el siguiente ejemplo:

// Action 1

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.enrolledFactors.length) {
    // ya inscrito, desafiar
    api.authentication.challengeWithAny(event.user.enrolledFactors.map(m => ({type: m.type})));
    if (event.user.app_metadata.isAdmin &&
        !event.user.enrolledFactors.some(m => m.type === 'webauthn-roaming')) {
          // si es administrador y no tiene una clave de seguridad, lo que significa que se usó un factor diferente, inscribirse ahora
          api.authentication.enrollWith({type: 'webauthn-roaming'})
        }
  }
  else {
    // no inscrito; elegir un factor para inscribirse ahora
    api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    if (event.user.app_metadata.isAdmin) {
      // un factor más para los administradores
      api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    }
  }
};

// Action 2

exports.onExecutePostLogin = async (event, api) => {
  function performed(type) {
    return event.authentication.methods.some(m => m.name === 'mfa' &&
           m.type === type &&
           Date.now() - new Date(m.timestamp).getTime() < 5000)
  }
  if (event.user.app_metadata.isAdmin) {
      // exigir que se usen ambos factores desafiando el que aún no se ha utilizado
      if (!performed('webauthn-roaming')) {
        api.authentication.challengeWith({type: 'webauthn-roaming'})
      }
      else if (!performed('otp')) {
        api.authentication.challengeWith({type: 'otp'})
      }
  }
};

Estas dos Actions se combinan para crear un escenario en el que los usuarios sin el rol de administrador deben inscribirse con una contraseña de un solo uso (OTP) o una clave de seguridad. Por el contrario, los usuarios con el rol de administrador deben inscribirse en ambos factores.

La Action 1 revisa app_metadata para determinar si el usuario es administrador y luego le solicita que se inscriba en factores específicos. Si un usuario administrador solo se ha inscrito en OTP, primero debe completar un desafío de OTP para completar la autenticación. Después, se le solicita que se inscriba con claves de seguridad (webauthn-roaming).

Para mantener seguras las cuentas de usuario, los usuarios deben completar un desafío de MFA con uno de sus enrolledFactors existentes antes de poder inscribirse en factores adicionales. Esta condición garantiza que pueda implementar de forma segura una política personalizada de inscripción en MFA después de que ya se haya utilizado una aplicación con distintos factores y configuraciones.

El flujo se pausa después de que se ejecuta la Action 1, y tanto event.user.enrolledFactors como event.authentication.methods se actualizarán cuando se ejecute la Action 2. Esto permite que el código de la Action tome decisiones basadas en datos reales del usuario cuando se ofrece a los usuarios la opción de completar un desafío o inscribirse en distintos factores.

Nota: Este método de ejecución de Actions solo se aplica a aquellas que contienen los comandos enrollWith o enrollWithAny. Las Actions que cumplen otros fines no se ven afectadas.

​

Antes de comenzar

Antes de poder personalizar sus flujos de MFA, debe configurar MFA en su inquilino y habilitar la opción Customize MFA Factors using Actions. Puede habilitar uno o más factores y definir sus políticas de MFA en su Auth0 Dashboard, en Security > Multi-factor Auth.

• Para obtener más información sobre el proceso de configuración, consulte Habilitar la autenticación multifactor.
• Para obtener información sobre cómo configurar factores específicos, consulte Factores de autenticación multifactor.

Para personalizar sus flujos, debe habilitar el interruptor Customize MFA Factors using Actions en la sección Additional Settings. Sus flujos personalizados no funcionarán correctamente si esta configuración no está habilitada.

Nota: Las Actions que usan los comandos enrollWith o enrollWithAny anulan cualquier política o regla existente que habilite o deshabilite MFA en un inquilino.

​

Personalice los flujos de inscripción de MFA

Después de configurar MFA para su inquilino, puede crear Actions de post-login para personalizar sus flujos de inscripción de MFA.

Las Actions (o una serie de Actions) de un inquilino solo pueden ejecutar cuatro de los siguientes comandos en cada flujo de usuario:

• enrollWith
• enrollWithAny
• challengeWith
• challengeWithAny

Si se supera este límite (es decir, si se intenta ejecutar un quinto comando de este tipo), se producirá un error de autenticación.

​

Cree su Action de post-login

Puede crear Actions desde Auth0 Dashboard:

1. Vaya a Actions > Flows y seleccione Login.

2. En el panel Add Action, seleccione el icono de signo más (+) y elija Build from scratch.

3. En la ventana emergente Create Action:

   • Introduzca un nombre para su Action.
   • Seleccione Login / Post-Login como desencadenador.
   • Use Node 22 (Recommended) como entorno de ejecución.

4. Revise la ventana emergente para asegurarse de que todo sea correcto. Luego, seleccione Create.

5. En el editor de código, agregue su código personalizado a la función onPostExecute.

6. Cuando el código esté listo, seleccione Deploy.

7. Seleccione Add to Flow en la notificación de implementación correcta.

   • Nota: Si la notificación se cierra, elija Back to Flow encima del editor de código.

8. Arrastre y suelte su nueva Action desde el panel Add Action a su flujo de Login. Luego, seleccione Apply.

Para realizar cambios adicionales después de guardar, vaya a Actions > Library > Custom y seleccione su Action. Luego puede actualizar el código y volver a implementarlo según sea necesario.

​

Pruebe su Action de post-login

Para asegurarse de que sus comandos funcionen correctamente, puede probar su Action desde el Auth0 Dashboard:

1. Vaya a Authentication > Authentication Profile.
2. Seleccione Try para abrir una pantalla de inicio de sesión de ejemplo en una pestaña nueva.
3. Introduzca sus credenciales y pruebe su nuevo flujo de MFA.

Si el flujo se completa correctamente, se mostrará una pantalla de confirmación. Si encuentra algún problema, puede actualizar el código yendo a Actions > Library > Custom en el Auth0 Dashboard.

​

Ejemplo de caso de uso

El siguiente ejemplo muestra un caso de uso común para personalizar los flujos de inscripción en MFA.

​

Muestre a los usuarios las opciones de MFA para inscribirse

En el siguiente ejemplo, se solicita a los usuarios OTP de forma predeterminada. Si lo desean, pueden usar el enlace Probar otro método para autenticarse con correo electrónico en su lugar.

​

Solución de problemas

Si experimenta errores o resultados inesperados en sus procesos de inscripción en MFA personalizados, puede usar la siguiente información para identificar y resolver estos problemas.

​

Registros del inquilino

Puede monitorizar sus inscripciones de MFA personalizadas mediante los registros del inquilino.

Los registros del inquilino están disponibles en el Auth0 Dashboard, en Monitoring > Logs. Como alternativa, puede recuperar los registros mediante la Management API.

Si usted o sus usuarios experimentan un comportamiento inesperado, revise los registros del inquilino y consulte los siguientes códigos de evento para obtener más información:

Escenario	Evento	Mensaje de error
Se le solicita a un usuario que se inscriba en un factor específico. Sin embargo, el factor solicitado cumple una de las siguientes condiciones: El factor no está habilitado en su inquilino. El factor no es compatible con el navegador del usuario. El usuario ya se ha inscrito en el factor solicitado. En este escenario, el usuario puede completar el flujo si hay factores alternativos disponibles.	w	Se usa una inscripción de MFA en una Action PostLogin, pero el factor solicitado ${factor.name} no está configurado correctamente. Habilite el factor solicitado y asegúrese de que el usuario no esté ya inscrito en él.
Se le solicita a un usuario que se inscriba en uno o varios factores, pero los factores proporcionados no pueden usarse para la inscripción. En este caso, el usuario no puede completar el flujo.	mfar	Se usa una inscripción de MFA en una Action PostLogin, pero los factores solicitados no están configurados correctamente. Para realizar MFA, habilite los factores solicitados y asegúrese de que el usuario no esté ya inscrito en ellos.
Un usuario intenta inscribirse en un factor nuevo sin completar al menos un desafío con una inscripción existente.	mfar	Se solicitó una inscripción de MFA, pero el usuario ya está inscrito en MFA. Complete al menos un desafío con un factor existente antes de inscribirse en uno nuevo.

​

Lista de verificación para la solución de problemas

La siguiente lista de verificación ofrece sugerencias adicionales para identificar y resolver problemas comunes con flujos de MFA personalizados.

1. La opción Customize MFA factors with Actions debe estar habilitada.

   • Vaya a Auth0 Dashboard > Security > Multi-factor Auth y asegúrese de que la opción de la sección Additional Settings esté habilitada.

2. Los factores a los que hacen referencia sus Actions deben estar habilitados en su inquilino.

   • Revise su código: Vaya a Auth0 Dashboard > Actions > Library > Custom y revise el código de sus Actions. Asegúrese de que todos los factores referenciados sean aplicables a sus casos de uso.
   • Revise sus factores: Vaya a Auth0 Dashboard > Security > Multi-factor Auth y asegúrese de que todos los factores referenciados en sus Actions estén habilitados.

3. Asegúrese de que sus Actions se hayan implementado y guardado en su Pipeline.

   1. Vaya a Auth0 Dashboard > Actions > Library > Custom. Ubique su Action en la lista y asegúrese de que su estado sea Deployed. Si aparece un estado diferente, abra su Action, revise el código y haga clic en Deploy en la esquina superior derecha.
   2. Vaya a Auth0 Dashboard > Actions > Library > Flows y seleccione Login. Asegúrese de que su Action aparezca en el flujo. Si no es así, abra la pestaña Custom del panel Add Action y arrastre y suelte su Action en el flujo de Login. Luego, seleccione Apply.

4. Asegúrese de haber actualizado a la versión más reciente de las Actions post-login.

   • Vaya a Auth0 Dashboard > Actions > Library > Custom y seleccione su Action. Si su Action está desactualizada, verá un banner amarillo que le indicará que actualice la Action. Si aparece el banner, seleccione Update.
   • También puede especificar la versión más reciente de las Actions post-login para la implementación al usar Deploy CLI. Para obtener más información, consulte Configure the Deploy CLI.