Gestiona MFA por API

MFA usa dos APIs de Access Manager:

Identity inscribe métodos y gestiona la configuración MFA del usuario.
Auth completa el segundo paso de verificación durante el inicio de sesión.

Lee Autenticación multifactor antes de integrar estas operaciones.

Operaciones de inscripción de cuentas

La API de Identity expone estas operaciones de autoservicio:

Operación	Propósito
`POST /v1/users/{id}/mfa/setup`	Inicia la configuración de `app` o `email`.
`POST /v1/users/{id}/mfa/verify`	Verifica el código de acceso de configuración.
`POST /v1/users/{id}/mfa/enable`	Activa el método verificado.
`GET /v1/users/{id}/mfa`	Lee el estado MFA actual y los métodos activados.
`PATCH /v1/users/{id}/mfa/preferred`	Selecciona el método activado preferido.
`DELETE /v1/users/{id}/mfa`	Desactiva todos los métodos.
`DELETE /v1/users/{id}/mfa/{mfaType}`	Desactiva un método.
`POST /v1/users/{id}/mfa/recovery-codes`	Genera un nuevo conjunto de códigos de recuperación. El conjunto anterior deja de funcionar.

Las operaciones estándar son de autoservicio. El sujeto del bearer token debe coincidir con {id}.

Inicia la configuración

Envía el método en el cuerpo de la solicitud:

Request

{
  "mfaType": "app"
}

Esta función admite app y email. La configuración de una aplicación de autenticación devuelve un secreto, una URL de código QR y códigos de recuperación. La configuración por correo electrónico devuelve códigos de recuperación y envía un código de acceso a la dirección de correo electrónico guardada del usuario.

Verifica la configuración

Envía el código de acceso de configuración de 6 a 8 caracteres y el método. La verificación de una aplicación de autenticación también necesita el secreto devuelto por la configuración.

Request

{
  "mfaType": "app",
  "passcode": "123456",
  "secret": "setup-secret"
}

Activa el método

Después de la verificación, activa el método con uno de los códigos de recuperación de la respuesta de configuración. La activación de una aplicación de autenticación también necesita el secreto de configuración.

Request

{
  "mfaType": "app",
  "secret": "setup-secret",
  "recoveryCode": "recovery-code"
}

Trata los secretos de configuración y los códigos de recuperación como credenciales. No los registres en logs ni los almacenes en el control de código fuente.

Desactivar MFA o eliminar un método

Para desactivar MFA, envía el código que describe la referencia Deshabilitar MFA. Para eliminar la aplicación de autenticación o el método de correo electrónico, envía un código de ese método. Para recibir el código por correo electrónico, llama a POST /v1/users/{id}/mfa/disable/challenge. Solo el propio usuario puede solicitarlo, y solo cuando el método de correo electrónico está activado. El código es válido durante 10 minutos y admite 5 intentos incorrectos. Un usuario puede solicitar 3 códigos en 15 minutos.

Operaciones de administrador

Un administrador gestiona los métodos de otro usuario con dos operaciones más. {id} es el usuario de destino. El bearer token necesita el permiso mfa-admin con la acción post para activar un método y la acción delete para eliminar uno.

Operación	Propósito
`POST /v1/users/{id}/mfa/admin/enable`	Activa `email` para el usuario de destino sin configuración ni verificación. La respuesta contiene los códigos de recuperación del usuario de destino.
`DELETE /v1/users/{id}/mfa/admin/{mfaType}`	Elimina un método (`app`, `email` o una inscripción heredada de `sms`) del usuario de destino. La operación no pide código.

Operaciones de inicio de sesión

El primer factor usa Solicitar token de acceso. Cuando el usuario tiene MFA activada, la operación devuelve una respuesta de desafío MFA en lugar de tokens de acceso. La respuesta incluye:

mfaRequired: true.
un mfaToken de corta duración.
los métodos activados.
el método preferido.

Inscribe un método exigido

Cuando el usuario no tiene ningún método MFA y la organización exige uno, Solicitar token de acceso responde 401 con el error AUT-0019 en lugar de un desafío MFA. Verificar inicio de sesión MFA da la misma respuesta cuando el usuario tiene un método, pero no todos los métodos exigidos. El cuerpo del error también tiene:

mfaToken: un token válido solo para la inscripción.
availableMethods: los métodos que el usuario puede inscribir, app o email.

Inicia la configuración con Iniciar inscripción en MFA.
Request
{ "mfaToken": "enrollment-mfa-token", "mfaType": "app" }
Para app, la respuesta tiene un secret y una url para la aplicación de autenticación. Para email, Access Manager envía un código a la dirección de correo electrónico guardada del usuario. La respuesta siempre tiene un código de recuperación en recoveryCodes. Guárdalo: no podrás recuperarlo más adelante. Una nueva llamada de configuración reemplaza la configuración anterior.
Confirma el método con Confirmar inscripción en MFA. Envía el código de acceso de la aplicación de autenticación o del correo electrónico.
Request
{ "mfaToken": "enrollment-mfa-token", "mfaType": "app", "passcode": "123456" }
Access Manager activa el método y devuelve una respuesta de desafío MFA con el mismo mfaToken. Continúa con Solicita la entrega por correo electrónico para el correo electrónico y, después, con Verifica el segundo factor.

Los códigos de acceso incorrectos cuentan para el mismo límite por usuario de la verificación (AUT-0018). El token MFA conserva la duración que tenía en el primer factor, así que completa la inscripción y la verificación dentro de una sesión MFA.

Solicita la entrega por correo electrónico

Usa Iniciar desafío MFA para el correo electrónico.

Request

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "email"
}

No solicites la entrega para app. La aplicación de autenticación genera el código de acceso localmente.

Verifica el segundo factor

Usa Verificar inicio de sesión MFA. Envía passcode o recoveryCode, pero no ambos.

Passcode

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "passcode": "123456"
}

Recovery code

{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "recoveryCode": "unused-recovery-code"
}

Una verificación exitosa devuelve la respuesta estándar de token de acceso, a menos que el usuario aún tenga un método exigido por inscribir (AUT-0019). Un código de recuperación se consume después de un uso exitoso.

Manejo de errores

Los errores importantes de inicio de sesión incluyen:

Código	Significado
`AUT-0016`	El código de acceso no es válido o, en Iniciar inscripción en MFA, el método no es uno que el usuario deba inscribir.
`AUT-0017`	La sesión MFA expiró, o el token MFA no es válido para este paso. Reinicia el inicio de sesión.
`AUT-0018`	Se excedió el límite de verificaciones.
`AUT-0019`	La organización exige un método MFA que el usuario no ha inscrito. Inscríbelo con el token MFA devuelto.
`AUT-0020`	El token MFA no es válido.

Identity también puede rechazar un método no admitido, un secreto de configuración faltante, un destino de correo electrónico faltante o una configuración no verificada. Consulta la lista de errores de Access Manager para conocer el envelope de error completo y los códigos actuales.

Introducción

Access Manager

Console

Streaming Hub

Multi-tenancy

Observabilidad

Narya

Lifecycle Management

Licenciamiento

Gestiona MFA por API

Operaciones de inscripción de cuentas

Inicia la configuración

Verifica la configuración

Activa el método

Desactivar MFA o eliminar un método

Operaciones de administrador

Operaciones de inicio de sesión

Inscribe un método exigido

Solicita la entrega por correo electrónico

Verifica el segundo factor

Manejo de errores

Páginas relacionadas

Completa MFA en Console

APIs de Identity

​Operaciones de inscripción de cuentas

​Inicia la configuración

​Verifica la configuración

​Activa el método

​Desactivar MFA o eliminar un método

​Operaciones de administrador

​Operaciones de inicio de sesión

​Inscribe un método exigido

​Solicita la entrega por correo electrónico

​Verifica el segundo factor

​Manejo de errores

​Páginas relacionadas

Completa MFA en Console

APIs de Identity

Operaciones de inscripción de cuentas

Inicia la configuración

Verifica la configuración

Activa el método

Desactivar MFA o eliminar un método

Operaciones de administrador

Operaciones de inicio de sesión

Inscribe un método exigido

Solicita la entrega por correo electrónico

Verifica el segundo factor

Manejo de errores

Páginas relacionadas