Personalizar la selección de MFA para Universal Login

Personalice los flujos de MFA con Actions de post-login para requerir factores específicos o secuencias de factores a los usuarios.

Auth0 admite diversos factores para proteger el acceso de los usuarios con autenticación multifactor (MFA). Con Actions de post-login, puede personalizar sus flujos de MFA para requerir un factor específico o una secuencia de factores a los usuarios. También puede usar información contextual sobre los usuarios y sus organizaciones para crear experiencias más personalizadas. Por ejemplo, puede personalizar sus flujos para requerir factores específicos a los usuarios en función de su pertenencia a determinadas Organizaciones o de los roles de usuario que tengan asignados.

• Esta función le permite personalizar sus flujos de selección de MFA. Si desea personalizar sus flujos de inscripción en MFA, consulte Personalizar las inscripciones en MFA en Universal Login.
• Solo puede personalizar flujos de MFA con Actions si usa Universal Login.
• Algunos de los métodos detallados solo pueden usarse en Universal Login y no en Classic Login. Para obtener más información, lea Personalizar MFA para Classic Login.

​

Cómo funciona

Puedes usar Actions para personalizar tus flujos de MFA. En concreto, puedes modificar el trigger post-login del flujo de inicio de sesión con los siguientes métodos de la API de autenticación:

• challengeWith: Especifica el factor o los factores que los usuarios deben usar para autenticarse, como una contraseña de un solo uso (OTP). Este método presenta a los usuarios un desafío predeterminado y, opcionalmente, puede dar acceso a un selector de factores que les permite elegir un método de autenticación diferente.

• challengeWithAny: Establece un grupo de factores entre los que los usuarios pueden elegir al autenticarse, como correo electrónico y OTP. De forma predeterminada, este método presenta a los usuarios un selector de factores en lugar de un desafío específico, de acuerdo con las siguientes condiciones:

  • Si se especifican dos o más factores, se muestra al usuario un selector de factores.
  • Si el usuario solo se ha inscrito en uno de los factores especificados (o si solo se proporciona un factor), se omite el selector de factores.
  • Si el usuario no se ha inscrito en ninguno de los factores especificados, el comando falla.

Puedes usar una combinación de estos métodos para adaptar tus flujos de MFA según sea necesario. También puedes incorporar metadatos de usuario, como roles o factores usados anteriormente, en estos métodos para crear flujos más personalizados.

Al elegir desafíos de MFA para tus comandos, puedes usar los factores que se enumeran a continuación o el valor enrolledFactors. enrolledFactors representa la lista de factores activos asociados a la cuenta de un usuario.

• otp

• email

• push-notification

  • otpFallback

• phone

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

• webauthn-platform

• webauthn-roaming

La matriz event.authentication.methods incluye un campo type cuando el nombre del método se establece en mfa. type es una cadena que contiene valores de factor que coinciden con los usados por el campo type de enrolledFactors (enumerados arriba). Cuando se realiza un desafío de MFA, methods contiene un objeto con name:mfa y type establecido en el factor usado para ese desafío. methods solo se actualiza cuando comienza una Action. Para ver los resultados de un desafío, debes acceder a methods en la siguiente Action del flujo.

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

• Triggers de Actions: post-login - Objeto Event
• Triggers de Actions: post-login - Objeto API

​

Flujos secuenciados y contextuales

Con los comandos challengeWith o challengeWithAny, puede usar información contextual para determinar cuál es la mejor verificación o la mejor secuencia de verificaciones que presentar a los usuarios. En concreto, puede aprovechar lo siguiente:

• Flujos secuenciados: Someta a los usuarios a una serie de factores diferentes en un orden específico.
• Flujos contextuales: Determine con qué factor verificar al usuario a continuación en función de las verificaciones anteriores del flujo.

Para ilustrar estos flujos, considere el siguiente ejemplo:

// ACCIÓN 1 

exports.onExecutePostLogin = async (event, api) => {

   api.authentication.challengeWithAny([{ type: 'phone'}, { type: 'push-notification' }]);

} 

// ============================================ 

// ACCIÓN 2 

// Decidir según lo que hizo el usuario en la acción anterior 

exports.onExecutePostLogin = async (event, api) => { 

    if(event.authentication.methods.find(m => m.type === 'phone') && event.authorization?.roles.includes('admin')) { 

        api.authentication.challengeWith({ type: 'push-notification' }); 

    }

}

En este escenario, primero se solicita al usuario la verificación por SMS mediante el comando challengeWithAny en la Action 1. Luego, la Action 2 solicita al usuario una notificación push porque tiene el rol de usuario Admin y, además, completó la verificación por SMS.

En este flujo, puede decidir qué factor solicitar al usuario por los siguientes motivos:

1. El flujo se pausa después de ejecutar la Action 1.
2. El usuario completa el flujo de MFA iniciado por la Action 1.
3. event.authentication.methods.type en la Action 2 se rellena con información de la verificación de MFA anterior.
4. El flujo se reanuda para ejecutar la Action 2 con la información contextual de la Action 1.

Aunque este ejemplo ofrece una experiencia similar a usar redirecciones en sus Actions, los comandos challengeWith y challengeWithAny ofrecen las siguientes ventajas específicas:

• Los flujos se pausan después de cada comando, lo que le permite recopilar información del usuario que puede usarse en Actions posteriores. En cambio, las redirecciones solo se producen una vez, como comando final de un flujo.
• La MFA se activa después de ejecutar cada Action que contiene comandos challengeWith o challengeWithAny. Con las redirecciones, la MFA se ejecuta como la Action final del pipeline.

Nota: Este método de ejecutar Actions solo se aplica a aquellas que contienen comandos challengeWith o challengeWithAny. Las Actions que cumplen otras funciones no se ven afectadas.

​

Antes de comenzar

Antes de personalizar sus flujos de MFA, primero debe habilitar MFA en su inquilino y pedir a sus usuarios que se inscriban en los factores adecuados.

​

Prepare su inquilino

Para comenzar, configure MFA en su inquilino y habilite la opción Customize MFA Factors using Actions. Puede configurar uno o varios factores y definir sus políticas de MFA en el Auth0 Dashboard, en Security > Multifactor Auth.

• Para obtener más información sobre el proceso de configuración, consulte Enable Multi-Factor Authentication.
• Para obtener información sobre cómo configurar factores específicos, consulte Multi-factor Authentication Factors.

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 opción no está habilitada.

• Las Actions que invocan los comandos challengeWith y challengeWithAny anulan cualquier desafío habilitado mediante api.multifactor.enable. También tienen prioridad sobre la configuración de MFA disponible en Define Policies.
• Para garantizar que los usuarios completen MFA al intentar acceder a su aplicación, establezca la opción Require Multi-factor Auth en Use Adaptive MFA o Always. En caso de que el código de sus Actions no se ejecute, esta opción sirve como respaldo y evita que los usuarios eludan MFA.
• Si desea usar evaluadores de riesgo en sus comandos, habilite el interruptor Adaptive MFA Risk Assessment y use event.authentication.riskAssessment en el código post-login de sus Actions.

​

Inscriba a los usuarios en los factores

Una vez que MFA esté configurado, asegúrese de que sus usuarios se inscriban en uno o más de los factores que habilitó. Los usuarios deben inscribirse en autenticadores antes de que los comandos post-login de Action puedan solicitarles una verificación.

Después de que un usuario se registre o se cree en su inquilino, puede crear inscripciones con el endpoint authentication-methods de la Management API, o bien puede administrar directamente las inscripciones de los usuarios desde sus páginas de perfil en el Auth0 Dashboard.

​

Personalice sus flujos de MFA

Una vez que su inquilino esté listo, puede crear Actions de post-login para personalizar sus flujos de MFA. A continuación, se incluyen los pasos y algunos casos de uso de ejemplo.

Las Actions (o una serie de Actions) en un inquilino solo pueden ejecutar cuatro de los siguientes comandos por 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.

​

Crea tu Action posterior al inicio de sesión

1. En tu Auth0 Dashboard, ve a Actions > Flows y selecciona Login.

2. En Add Action, selecciona Custom y elige Create Action.

3. En la ventana emergente Create Action:

   • Introduce un nombre para tu Action.
   • Selecciona Login / Post-Login como desencadenador.
   • Usa Node 22 (Recommended) como entorno de ejecución.

4. Revisa la ventana emergente para asegurarte de que la información sea correcta. Luego, selecciona Create.

5. Después de crearla, el editor de código muestra la función onPostExecute. Agrega a esa función tu código personalizado o el código de ejemplo.

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

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

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

8. Arrastra y suelta tu nueva Action desde el panel Add Action a tu flujo de Login. Luego, selecciona Apply.

Para realizar actualizaciones adicionales en tu Action, ve a Actions > Library > Custom y selecciona tu Action. Luego, puedes actualizar y volver a implementar tu código según sea necesario.

Al agregar una redirección a tu flujo de MFA, asegúrate de que tu Action cumpla las siguientes condiciones para evitar que los usuarios omitan o eludan MFA:

• El comando de redirección (sendUserTo) debe estar en una Action independiente de tus comandos de MFA.
• La Action de redirección debe ser la última Action que se ejecute en tu flujo.

Para obtener más información sobre las redirecciones, consulta Redireccionar con Actions.

​

Pruebe su Action de post-login

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

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

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

​

Ejemplos de casos de uso

Los ejemplos siguientes muestran casos de uso habituales para personalizar los flujos de MFA.

​

Usa las inscripciones actuales para determinar el método de desafío

El siguiente ejemplo presenta un desafío de MFA a un usuario si está inscrito en los siguientes factores:

• Contraseña de un solo uso (OTP)
• Teléfono

exports.onExecutePostLogin = async (event, api) => {

 api.authentication.challengeWithAny([{type: 'otp'}, {type: 'phone'}]);

}

​

Usar roles para determinar el método de verificación adicional

El siguiente ejemplo solicita OTP a todos los usuarios. Si un usuario tiene el rol de Admin y requiere un nivel de acceso más alto a la aplicación, se le solicita un factor adicional como forma de autenticación escalonada.

exports.onExecutePostLogin = async (event, api) => {
    api.authentication.challengeWith({type: 'otp'});

    const isAdmin = event.authorization?.roles.includes('admin');
    if(isAdmin) {
        api.authentication.challengeWith({type: 'phone'});
    }
}

​

Usa metadatos para determinar el tipo de desafío

En este ejemplo, los factores de MFA están habilitados a nivel de Organización. Este ejemplo usa distintas categorías de metadatos para determinar el desafío adecuado para cada usuario:

• Metadatos de la organización: Datos a nivel de organización, como los factores específicos habilitados para una Organización.
• Metadatos del usuario: Datos a nivel de usuario, como si un usuario tiene un número de teléfono asociado a su perfil.

exports.onExecutePostLogin = async (event, api) => {
  const orgFactors = event.organization?.metadata.factors.split(',') ?? [];

  // Obtener la intersección de factores disponibles para el usuario y factores habilitados para la organización
  const availableFactors = orgFactors.filter(f => event.user?.enrolledFactors?.some(ef => ef.type === f));

  // Preferir push si está disponible
  if(availableFactors.includes('push-notification')) {
    api.authentication.challengeWith({ type: 'push-notification' });
    return;
  }

  // Si el usuario tiene un número de teléfono verificado y la organización
  // permite SMS y correo electrónico, preferir SMS y permitir correo electrónico como alternativa
  // si está disponible
  if(event.user.phone_number && 
     event.user.phone_verified && 
     availableFactors.includes('phone')) {
    if(availableFactors.includes('email')) {
      api.authentication.challengeWith({ type: 'phone' }, {
        additionalFactors: [{
          type: 'email'
        }]
      });
    } else {
      api.authentication.challengeWith({ type: 'phone' });
    }

    return;
  }

  // Si las notificaciones push y/o el teléfono no pudieron priorizarse, recurrir al correo electrónico
  // si está habilitado para la organización; de lo contrario, denegar el acceso.
  if(availableFactors.includes('email')) {
    api.authentication.challengeWith({ type: "email" });
    return;
  }

  api.access.deny("No MFA factors available for this org + user");
};

​

Permitir que los usuarios seleccionen un método de autenticación alternativo

Para ofrecer una experiencia más flexible, puede mostrar a los usuarios un enlace de Probar otro método como parte de la verificación de MFA. Este enlace permite a los usuarios seleccionar un método de autenticación distinto del método predeterminado.

Para lograrlo, incluya el parámetro additionalFactors en su código de Actions. Puede configurar este parámetro para un factor específico para todos los usuarios o usar enrolledFactors para permitir que los usuarios elijan su factor preferido.

Factor específico

El siguiente ejemplo solicita OTP de forma predeterminada. Si lo desean, los usuarios pueden acceder al enlace Probar otro método para autenticarse con correo electrónico en su lugar.

exports.onExecutePostLogin = async (event, api) => {
  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: [{type: 'email'}] })
};

Factores inscritos

En el siguiente ejemplo, se solicita OTP a los usuarios de forma predeterminada. Si lo desean, pueden acceder al enlace Try Another Method para autenticarse con alguno de sus otros factores inscritos.

exports.onExecutePostLogin = async (event, api) => {
  const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));

  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: enrolledFactors })
};

​

Usa Adaptive MFA para determinar cuándo requerir una verificación adicional a los usuarios

El siguiente ejemplo usa Adaptive MFA para determinar si se debe requerir una verificación adicional a los usuarios.

Adaptive MFA es una política de MFA flexible que protege a tu inquilino de actores maliciosos al evaluar el riesgo potencial durante las transacciones de inicio de sesión y solicitar a los usuarios una verificación adicional cuando corresponde.

En este caso, se solicita MFA a los usuarios si inician sesión desde un dispositivo no reconocido y su puntuación general de confianza es baja o media.

/**
* Manejador que se llamará durante la ejecución de un flujo PostLogin.
*
* @param {Event} event - Detalles sobre el usuario y el contexto en el que está iniciando sesión.
* @param {PostLoginAPI} api - Interfaz cuyos métodos pueden usarse para cambiar el comportamiento del inicio de sesión.
*/
exports.onExecutePostLogin = async (event, api) => {
  if (event.authentication?.riskAssessment?.assessments.NewDevice) {

  // Condición de ejemplo: solicitar MFA solo en función del nivel de confianza 
    // de NewDevice; esto solicitará MFA cuando un usuario inicie sesión 
    // desde un dispositivo desconocido.
    let shouldPromptMfa;

    switch (event.authentication.riskAssessment.assessments.NewDevice.confidence) {
      case 'low':
      case 'medium':
        shouldPromptMfa = true;
        break;
      case 'high':
        shouldPromptMfa = false;
        break;
      case 'neutral':
        // Cuando este evaluador no dispone de información útil sobre la confianza, 
        // no solicitar MFA.
        shouldPromptMfa = false;
        break;
    }

      // Solo tiene sentido solicitar MFA cuando el usuario tiene al menos un 
      // factor de MFA inscrito.
    const canPromptMfa = event.user.enrolledFactors?.length > 0;

    if (shouldPromptMfa && canPromptMfa) {
      const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));
      api.authentication.challengeWithAny(enrolledFactors);
    }

  }

};

​

Usar Actions para solicitar MFA a los usuarios

Puede usar Actions para personalizar los flujos de MFA modificando el desencadenador post-login del flujo de inicio de sesión. En este ejemplo, se utiliza el método de autenticación phone y preferredMethod: 'both', que hace referencia a los factores de MFA activos asociados con la cuenta de un usuario. Para obtener más información, consulte Desencadenadores de Actions: post-login - objeto de evento.

api.authentication.challengeWith({ 
  type: 'phone', 
  options: { preferredMethod: 'both'} 
});

​

Solución de problemas

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

​

Registros del tenant

Puede supervisar sus flujos de MFA personalizados a través de los registros del inquilino.

Los registros del tenant 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 para consultar los siguientes códigos de evento y obtener más información:

Escenario	Código de evento	Error descriptivo
A un usuario se le solicita autenticación multifactor, pero ninguno de los factores solicitados puede usarse como desafío. En este caso, el usuario no puede completar MFA.	mfar	Este escenario genera el siguiente mensaje de error: Se usa un desafío de MFA en una Action de PostLogin, pero los factores solicitados no están configurados correctamente. Para realizar MFA, habilite los factores solicitados y asegúrese de que el usuario esté inscrito en ellos.
A un usuario se le solicita autenticación multifactor, pero uno de los factores solicitados no puede usarse como desafío. En este caso, el usuario puede completar MFA con otro de los factores solicitados.	w	Este escenario genera el siguiente mensaje de advertencia: Se usa un desafío de MFA en una Action de PostLogin, pero el factor solicitado {factor name} no está configurado correctamente. Habilite el factor solicitado y asegúrese de que el usuario esté inscrito en él.

​

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

La siguiente lista de comprobació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 tenant.

   • 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 a los que se hace referencia 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 a los que se hace referencia en sus Actions estén habilitados.

3. Los usuarios deben estar inscritos en los factores a los que hacen referencia sus Actions.

   • Si una persona recibe un error, revise los detalles de su usuario para asegurarse de que esté inscrita en los factores correctos. Vaya a Auth0 Dashboard > User Management > Users y seleccione su nombre de la lista.

     • Revise la sección Multi-factor Authentication en la pestaña Detail para verificar sus inscripciones. Si el usuario no está inscrito, puede usar el enlace Send an enrollment invitation disponible en esta sección.
     • Como alternativa, verifique las inscripciones del usuario en la pestaña Raw JSON. Esta información también puede recuperarse con la Management API. Sin embargo, es importante tener en cuenta que la API no muestra los autenticadores inscritos automáticamente, como los factores de correo electrónico configurados mediante un enlace de verificación por correo electrónico.

   • Si los usuarios no están inscritos en los factores adecuados, puede crear inscripciones con el endpoint authentication-methods de la Management API. También puede administrar directamente las inscripciones de los usuarios desde sus páginas de perfil en el Auth0 Dashboard.

4. Asegúrese de que sus Actions se hayan desplegado y guardado en su Pipeline.

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

5. 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 pedirá 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 su implementación con Deploy CLI. Para obtener más información, consulte Configure the Deploy CLI.