Documentación de Oracle Cloud Infrastructure

Uso de la API de MFA a demanda para desarrollar una página de conexión personalizada

Este caso de uso proporciona un ejemplo paso a paso del uso de la API de REST de dominios de identidad para autenticar usuarios y realizar autenticación e inscripción multifactor.

Nota

Utilice esta API de autenticación solo si va a crear su propia experiencia de conexión integral mediante el desarrollo de una aplicación de conexión personalizada que utilizarán los dominios de identidad.
Nota

Esta API de autenticación no se puede utilizar para integrar las aplicaciones con los dominios de identidad con fines de conexión única.

La API de MFA de On Demand se basa en el concepto de una máquina de estado. Las respuestas de solicitud informan a un cliente de aplicación lo que debe hacerse a continuación en lugar de exigir a los usuarios que tengan habilitadas las cookies de terceros en sus navegadores. Las cookies de terceros activadas en los navegadores pueden plantear problemas, especialmente para las aplicaciones B2C donde no se pueden aplicar controles sobre el comportamiento del usuario final. El requestState proporcionado en cada respuesta de solicitud se utiliza en la siguiente solicitud, proporcionando al cliente la información que necesita para procesar la solicitud y, a continuación, proporcionar el siguiente juego de operaciones permitido.

La API de MFA de On Demand puede:
  • Permite admitir la inscripción de usuarios con factores de MFA activados por el administrador.
  • Refuerce la seguridad de la autenticación basada en contraseñas mediante la autenticación multifactor (MFA) al requerir una verificación adicional, como el uso de un código de acceso de un solo uso basado en tiempo o un código de acceso SMS.
  • Realice la inscripción de MFA, la verificación de MFA y la gestión del factor de autenticación de usuarios.

En este caso de uso se incluyen los siguientes conjuntos de ejemplo:

Inscripción de factor con verificación

Inscripción de factor con verificación

Estos casos de uso proporcionan solicitudes de ejemplo mediante la API de REST de dominios de identidad que permite a un usuario inscribirse en factores de MFA.

Los siguientes casos de uso le guiarán por los pasos para inscribir diferentes factores de MFA mediante la API de REST:

Recuperar factores inscritos de un usuario

Este caso de uso proporciona un ejemplo paso a paso del uso de la API de verificación de dominios de identidad para recuperar los factores en los que está inscrito un usuario.

En estos pasos, se asume que los factores relevantes de MFA se activan mediante Configurar valores de autenticación multifactor.

Descargue la recopilación de ejemplos de casos de uso de autenticación de dominios de identidad y el archivo de variables globales de la carpeta idcs-factor-enrollment-api en el repositorio idm-samples GitHub y, luego, impórtelos en Postman.

El paso que se debe seguir en este caso de uso depende de si desea solicitar mediante userGUID o User Name:
Nota

Los ejemplos de esta sección utilizan userGUID en las solicitudes. Puede solicitar userGUID y userOcid en sus solicitudes.

Paso 1: Obtener Factores Inscritos para un Usuario por userGUID

Este paso obtiene los factores inscritos para un usuario según userGUID o el nombre de usuario.

Ejemplo de solicitud 

GET {{HOST}}/mfa/v1/users/{{userGUID}}/factors

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON:


{
    "userGUID": "7b3d902ab05b4214bae6b2924ca6be21",
    "status": "success",
    "preferredFactorId": "b3e04149d958437b9b801fa70c33ca70",
    "preferredMethod": "EMAIL",
    "factors": [
        {
            "factorId": "SecurityQuestions",
            "methods": [
                "SECURITY_QUESTIONS"
            ]
        },
        {
            "displayName": "+155XXXXX555",
            "factorId": "83889faeacaf4592a964405f87506fc6",
            "methods": [
                "SMS"
            ]
        },
        {
            "displayName": "uxxr1@example.com",
            "factorId": "b3e04149d958437b9b801fa70c33ca70",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        }
    ]
}

La respuesta contiene los detalles de userGUID, el factor preferido y el factor inscrito.

Paso 2: Obtener factores inscritos para un usuario mediante filtros

Puede obtener factores de inscripción para un usuario mediante el nombre de usuario o el GUID de usuario. Se aceptan los siguientes valores userIdType:

  • USER_GUID: por ejemplo, aquí userId debe contener USER_GUID como "7b3d902ab05b4214"
  • USER_NAME: por ejemplo, aquí userId debe contener USER_NAME, como John.

Ejemplo de solicitud para recuperar los factores inscritos según el nombre de usuario

En el siguiente ejemplo se muestra el ejemplo de solicitud para obtener los factores inscritos para un usuario en función de su nombre de usuario en formato JSON:

GET {{HOST}}/mfa/v1/users?userId=user1@example.com&userIdType=USER_NAME&attributes=factors

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

La respuesta contiene los detalles de userGUID, el factor preferido y el factor inscrito.

Ejemplo de solicitud para recuperar los factores inscritos según el GUID de usuario

En el siguiente ejemplo se muestra el ejemplo de solicitud para obtener los factores inscritos para un usuario según su GUID de usuario en formato JSON:

GET {{HOST}}/mfa/v1/users?userId=589879c55b7340518141eab82493f0cc&userIdType=USER_GUID&attributes=factors

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON:

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

La respuesta contiene los detalles de userGUID, el factor preferido y el factor inscrito.

Iniciar y verificar el factor preferido

Este caso de uso proporciona un ejemplo paso a paso del uso de la API de inscripción en factores de dominios de identidad para inscribirse en la autenticación multifactor (MFA) con verificación de factores.

En estos pasos, se asume que los factores relevantes de MFA se activan mediante Configurar valores de autenticación multifactor.

Descargue la recopilación de ejemplos de casos de uso de autenticación de dominios de identidad y el archivo de variables globales de la carpeta idcs-factor-verification-api en el repositorio idm-samples GitHub y, a continuación, impórtelos en Postman.

Descargue la recopilación y el archivo de variables globales de la carpeta idcs-factor-verification-api en GitHub y, a continuación, impórtelos en Postman.

Use los siguientes pasos para el caso de uso. Cada paso contiene ejemplos de solicitud y respuesta:
Nota

Los ejemplos de esta sección utilizan userGUID en las solicitudes. Puede solicitar userGUID y userOcid en sus solicitudes.

Step1: inicio de la verificación del factor preferido

Este paso inicia la verificación del factor preferido de un usuario. Si necesita utilizar la API de factor de verificación sin proporcionar userGUID, puede proporcionar un ID único de usuario, como el nombre de usuario, como userId. userIdType en la solicitud indica el tipo de credencial que el usuario está transfiriendo como valor para userId. Se aceptan los siguientes valores userIdType:

  • USER_GUID: por ejemplo, aquí userId debe contener USER_GUID, como "7b3d902ab05b4214"
  • USER_NAME: por ejemplo, aquí userId debe contener USER_NAME, como John.

El atributo userId contiene el valor real de la credencial de usuario que se transfiere.

Ejemplo de solicitud

En el siguiente ejemplo se muestra la solicitud POST al punto final {{HOST}}/mfa/v1/requests en formato JSON.

{
   "userId":"{{userGUID}}",
   "userIdType": "USER_GUID"
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta de POST al punto final {{HOST}}/mfa/v1/requests en formato JSON después de iniciar el factor preferido en el ID preferido:


{     
"status": "success",
"requestId": "f843736e-cbd8-4548-b41f-343b624a79fc",
"userGUID": "589879c55b7340518141eab82493f0cc",  
"factorId": "88178d80636a428393a5674ba46dc867",   
"method": "SMS",   
"displayName": "+4455665455",   
"requestState": "GwHJr3RvycjNEv.....MhQTLmWYzA/LVp0s"
}

En la respuesta, el valor requestId es el identificador único generado para esta solicitud. Incluya requestId en cada llamada posterior para completar la verificación del factor. factorId es el dispositivo preferido en el que se inició. method es el factor que ha iniciado el usuario. requestState contiene los datos contextuales necesarios para procesar la solicitud.

En este ejemplo, se envía un otpCode (en caso de SMS y factor EMAIL) mediante SMS al dispositivo móvil del usuario.

Paso 2: Verificar el factor preferido

Este paso verifica el factor transfiriendo otpCode en una solicitud PATCH a {{HOST}}/mfa/v1/requests/{{requestId}}.

El cliente debe incluir los siguientes atributos:

  • otpCode: el código recibido por el usuario en su dispositivo
  • requestState: recibido en la respuesta del paso 1
  • requestId: recibido en la respuesta del paso 1

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido de la solicitud PATCH en formato JSON: 

{  
"otpCode":"170230", 
"requestState": "{{requestState}}" 
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{"status":"success"}

Correcto indica que la verificación se realizó correctamente.

Iniciar y verificar un factor de copia de seguridad

Este caso de uso proporciona un ejemplo detallado del uso de la API de verificación de dominios de identidad para completar la verificación de factores del factor de copia de seguridad.

En estos pasos, se asume que los factores relevantes de MFA se activan mediante Configurar valores de autenticación multifactor.

Descargue la recopilación de ejemplos de casos de uso de autenticación de dominios de identidad y el archivo de variables globales de la carpeta idcs-factor-verification-api en el repositorio idm-samples GitHub y, a continuación, impórtelos en Postman.

Use los siguientes pasos para el caso de uso. Cada paso contiene ejemplos de solicitud y respuesta:
Nota

Los ejemplos de esta sección utilizan userGUID en las solicitudes. Puede solicitar userGUID y userOcid en sus solicitudes.

Paso 1: Iniciar y verificar las preguntas de seguridad del factor de copia de seguridad

Este paso inicia la verificación del factor de copia de seguridad de un usuario. El cliente debe proporcionar factorId y method en la solicitud. Si necesita utilizar la API de factor de verificación sin proporcionar userGUID, puede proporcionar un ID único de usuario, como el nombre de usuario, como userId. userIdType en la solicitud indica el tipo de credencial que el usuario está transfiriendo como valor para userId. Se aceptan los siguientes valores userIdType:

  • USER_GUID: por ejemplo, aquí userId debe contener USER_GUID como "7b3d902ab05b4214".
  • USER_NAME: por ejemplo, aquí userId debe contener USER_NAME como Joe John.

El atributo userId contiene el valor real de la credencial de usuario que se transfiere.

Para obtener una lista de los factores inscritos y sus ID para un usuario, consulte el caso de uso Recuperar factores inscritos de un usuario. En este ejemplo, el factor de copia de seguridad seleccionado es Security Questions.

Ejemplo de solicitud para iniciar preguntas de seguridad de factor de copia de seguridad

En el siguiente ejemplo se muestra el contenido de la solicitud POST al punto final {{HOST}}/mfa/v1/requests/en formato JSON:

Nota

El valor factorId preferido contiene el ID único del factor preferido. En el caso de SECURITY_QUESTIONS, tendrá la cadena fija "SecurityQuestions".
{
    "userId":"{{userID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"SECURITY_QUESTIONS"
}

En la respuesta, el valor requestId es el identificador único generado para esta solicitud. Incluya requestId en cada llamada posterior para completar la verificación del factor. requestState contiene datos contextuales necesarios para procesar la solicitud.

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta en formato JSON para el método de copia de seguridad SEQURITY_QUESTIONS: 

{
    "status": "success",
    "requestId": "8da79411-5388-41ee-990e-935e74cb40f3",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "SecurityQuestions",
    "method": "SECURITY_QUESTIONS",
    "requestState": "hBJIvkyfsXBv....movYarft8HlYANV3c+0",
    "securityQuestions": [
        {
            "id": "MaidenName",
            "localizedText": "What's your mother's maiden name?"
        }
    ]
}

En la respuesta, el valor requestId es el identificador único generado para esta solicitud. Incluya requestId en cada llamada posterior para completar la verificación del factor. requestState contiene datos contextuales necesarios para procesar la solicitud. En este ejemplo, se devuelve una pregunta de la lista de preguntas inscritas a las que el usuario debe responder.

Ejemplo de solicitud para verificar preguntas de seguridad de factor de copia de seguridad

Este paso verifica el factor de copia de seguridad transfiriendo la respuesta a la pregunta de seguridad de una solicitud PATCH a {{HOST}}/mfa/v1/requests/{{requestID}}. El cliente debe incluir los siguientes atributos:

  • requestState: recibido en la respuesta del paso 1
  • securityQuestions id/answers: definido por el usuario durante la inscripción

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido de la solicitud PATCH en formato JSON para SECURITY_QUESTIONS: 
{
 "securityQuestions":[
        {
            "id":"MaidenName",
            "answer":"Smith"
        }
    ],
"requestState": "{{requestState}}"
 }

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{"status":"success"}

Correcto indica que la verificación se realizó correctamente.

Paso 2: Iniciar y verificar el factor de copia de seguridad CORREO ELECTRÓNICO

Este paso inicia la verificación de un factor de copia de seguridad EMAIL.

Ejemplo de solicitud para iniciar factor EMAIL

En el siguiente ejemplo se muestra el ejemplo de solicitud con formato JSON para el método preferido "EMAIL":

{
    "userId":"{{userID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"EMAIL"
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el ejemplo de respuesta para iniciar el factor EMAIL con formato JSON:

{ 
 "status":"success",
 "requestId":"<Request ID>",
 "userGUID":"<User GUID>",
 "factorId":"factorID",
 "method":"EMAIL",
 "displayName":"Joe John",
 "requestState":"QYV81R9eoagwWQ"
 }

Ejemplo de solicitud para verificar el factor EMAIL

En el siguiente ejemplo se muestra la solicitud PATCH en formato JSON para el factor EMAIL:

{
    "otpCode":"170230"
     "requestState": "QYV81R9eoagwWQ"
 }

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta en formato JSON para verificar el factor EMAIL: 

{"status":"success"}

Correcto indica que la verificación se realizó correctamente.

Devolver factores de OTP sin notificar al usuario

Este caso de uso proporciona un ejemplo de inicio de la API de MFA de On Demand para devolver factores de código de acceso de un solo uso (OTP) (SMS o correo electrónico o llamada telefónica) en una respuesta sin notificar al usuario.

Descargue la recopilación de ejemplos de casos de uso de autenticación de dominios de identidad y el archivo de variables globales de la carpeta idcs-factor-verification-api en el repositorio idm-samples GitHub y, a continuación, impórtelos en Postman.

En estos pasos, se asume que los factores relevantes de MFA se activan mediante Configurar valores de autenticación multifactor.

Carga útil de solicitud
Atributo Valores soportados/valores de muestra Con Varios Valores Detalles de Uso
userFlowControlledByExternalClient true / false false
Establecer esta opción en 
true
y la OTP se devolverá en la respuesta en el formato cifrado especificado.

Nota: El certificado utilizado para el cifrado se carga en la aplicación por adelantado y se hace referencia a él mediante el atributo x5t en el ejemplo de solicitud, como se indica a continuación.
x5t Cadena / X509 Huella en miniatura del certificado SHA-1

Cuando se especifica, el servicio utiliza este certificado cargado para cifrar los datos de OTP.

Nota: El atributo "x5t" debe coincidir con el certificado cargado.
Ejemplo de solicitud
{
    "userId":"<Unique Id>",
    "userIdType":"USER_NAME/USER_GUID",
    "userFlowControlledByExternalClient": true,
    "x5t" :"<certificate thumbprint>"
}
Carga Útil de Respuesta
Atributo Valores soportados/valores de muestra Con Varios Valores Detalles de Uso
otp

Asignar

"otp": {
    "value": "IMCw==",
    "alg": "RSAES-OAEP",
      "x5t": "<certificate thumbprint>"
 }
false

Cuando está presente en la respuesta, el atributo contiene la OTP cifrada con los siguientes detalles.

  • value: valor cifrado.
  • alg: algoritmo utilizado para el cifrado.
  • x5t: Huella en miniatura SHA-1 X509 del certificado utilizado para el cifrado.

Ejemplo de respuesta

{
    "status": "success",
    "requestId": "<Request ID>",
    "userGUID": "<User GUID>",
    "factorId": "<SMS/EMAIL/PHONE_CALL factor GUID>",
    "method": "SMS/EMAIL/PHONE_CALL",
    "displayName": "+91XXXXXXXX984",
    "requestState": "4p7ViEzP2bP1MIM",
    "otp": {
        "value": "<Encrypted OTP value>",
        "alg": "<Encryption algorithm>",
        "x5t": "<x5t of the certificate used to encrypt the OTP>"
           }
}

Inscripción de factor de autenticación con verificación de factor - SMS

Este caso de uso proporciona un ejemplo paso a paso del uso de la API de inscripción en factores de dominios de identidad para inscribirse en la autenticación multifactor (MFA) con verificación de factores.

En estos pasos, se asume que los factores relevantes de MFA se activan mediante Configurar valores de autenticación multifactor.

Descargue la recopilación de ejemplos de casos de uso de autenticación de dominios de identidad y el archivo de variables globales de la carpeta idcs-factor-enrollment-api en el repositorio idm-samples GitHub y, luego, impórtelos en Postman.

Use los siguientes pasos para el caso de uso. Cada paso contiene ejemplos de solicitud y respuesta:
Nota

Los ejemplos de esta sección utilizan userGUID en las solicitudes. Puede solicitar userGUID y userOcid en sus solicitudes.

Paso 1: Iniciar inscripción de factor de SMS

Este paso inicia la inscripción por SMS. El cliente debe incluir los siguientes atributos:

  • method: define la inscripción en el factor SMS
  • phoneNumber: define el número de teléfono al que se enviará el texto SMS
  • countryCode: define el código de país del número de teléfono al que se enviará el texto SMS

Ejemplo de solicitud

En el siguiente ejemplo se muestra la solicitud POST al punto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors en formato JSON:

{ 
"method": "SMS",
"countryCode": "+44", 
"mobileNumber": "1122334455", 
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{
"status": "success", 
"factorId": "88178d80636a428393a5674ba46dc867",
"factorStatus": "ENROLLMENT_INITIATED", 
"methods": [ "SMS" ],
"displayName": "+1122334455", 
"requestState": "QK1.....y+OFP//0" 
}

displayName es el número de móvil. Se enviará una otpCode al dispositivo móvil de los usuarios, que se utiliza para completar la inscripción.

Paso 1a: Reenviar la OTP

Si el usuario no recibe la OTP, en este ejemplo se muestra cómo solicitar que se vuelva a enviar una OTP. El cliente debe incluir los siguientes atributos:

requestState: recibido en la respuesta del paso 1

resendOtp: Booleano para indicar que se recibe la OTP

Ejemplo de solicitud

En el siguiente ejemplo se muestra la solicitud PATCH al punto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} en formato JSON:

{
 "resendOtp":true,
 "requestState": "QK1.....y+OFP//0"
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON:

{ 
"status": "success",
"factorId": "88178d80636a428393a5674ba46dc867", 
"factorStatus": "ENROLLMENT_INITIATED",
"methods": [ "SMS" ],
"displayName": "+445544455",
"requestState": "+HFVV...qgMUI" 
}

La respuesta contiene los siguientes parámetros:

  • requestState: que debe transferir el cliente en el siguiente paso
  • displayName: es el número de móvil que se está inscribiendo
  • method: Método de factor SMS
  • Identificador único factorId: generado para el factor que se está inscribiendo
Correcto indica que:
  • El userGUID que se ha proporcionado es válido
  • El usuario está activo
  • No se ha bloqueado la cuenta de usuario.
  • El factor SMS está activado

Paso 2: Activación del factor SMS

Este paso activa la inscripción de SMS para el usuario, en una solicitud PATCH al punto final /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

El cliente debe incluir los siguientes atributos:

  • otpCode: el código recibido por el usuario en su dispositivo
  • requestState: recibido en la respuesta del paso 1

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido de la solicitud PATCH en formato JSON: 

{  
"otpCode":"170230", 
"requestState": "{{requestState}}"
 }

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{"status":"success"}

Correcto indica que:

  • OTP es válido
  • El userGUID que se ha proporcionado es válido
  • El usuario está activo
  • No se ha bloqueado la cuenta de usuario.
  • El factor SMS está activado y el factor se ha inscrito correctamente

Ejemplos de Respuesta de Error

En el siguiente ejemplo se muestra el mensaje de error en formato JSON cuando userGUID no es válido. Obtiene un código de respuesta HTTP 404 si userGUID no es válido.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

En el siguiente ejemplo se muestra el mensaje de error en formato JSON cuando el usuario está bloqueado. Obtiene un código de respuesta HTTP 401.

{
    "status": "failed",
    "ecId": "0ISDCif1Qy6wg0000A8",
    "cause": [
        {
            "code": "AUTH-1010",
            "message": "Your account is locked.Contact your system administrator."
        }
    ]
}

Inscripción de factor de autenticación con verificación de factor - Correo electrónico

Este caso de uso proporciona un ejemplo paso a paso del uso de la API de inscripción en factores de dominios de identidad para inscribirse en la autenticación multifactor (MFA) con verificación de factores.

En estos pasos, se asume que los factores relevantes de MFA se activan mediante Configurar valores de autenticación multifactor.

Descargue la recopilación de ejemplos de casos de uso de autenticación de dominios de identidad y el archivo de variables globales de la carpeta idcs-factor-enrollment-api en el repositorio idm-samples GitHub y, luego, impórtelos en Postman.

Use los siguientes pasos para el caso de uso. Cada paso contiene ejemplos de solicitud y respuesta:
Nota

Los ejemplos de esta sección utilizan userGUID en las solicitudes. Puede solicitar userGUID y userOcid en sus solicitudes.

Paso 1: Iniciar inscripción de factor de correo electrónico

Este paso inicia la inscripción por correo electrónico. El cliente debe incluir el siguiente atributo:

  • method: define la inscripción en el correo electrónico. El usuario no transferirá el ID de correo electrónico. El ID de correo electrónico principal se recupera automáticamente del perfil del usuario.

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido de la solicitud POST al punto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors en formato JSON: 

{ 
"method": "EMAIL",
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{
    "status": "success",
    "factorId": "30db2274140043918edb033d9fe29ff3",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "EMAIL"
    ],
    "displayName": "user1@example.com",
    "requestState": "Vxar...bWTTA"
}

Se enviará una otpCode al ID de correo electrónico del usuario, que se utiliza para completar la inscripción.

La respuesta contiene:

  • requestState: que debe transferir el cliente en el siguiente paso
  • displayName: ID de correo electrónico del usuario inscrito
  • method: Método de factor CORREO ELECTRÓNICO

Correcto indica que:

Se inició la inscripción de factor.

Paso 1a: Reenviar la OTP

En el siguiente ejemplo se muestra la solicitud PATCH al punto final {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} en formato JSON.

Si el usuario no recibe la OTP, en este ejemplo se muestra cómo solicitar que se vuelva a enviar una OTP. El cliente debe incluir los siguientes atributos:

  • requestState: recibido en la respuesta del paso 1
  • resendOtp: para indicar que se recibe la OTP

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido de la solicitud PATCH en formato JSON: 

{  
"resendOtp":true, 
 "requestState": "QK1.....y+OFP//0"
 }

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{    
"status": "success",     
"factorId": "30db2274140043918edb033d9fe29ff3",
"factorStatus": "ENROLLMENT_INITIATED",   
"methods": ["EMAIL"],
"displayName": "username@example.com", 
"requestState": "AmgsMN.....2sk4SI" 
}

La respuesta contiene:

  • requestState: que debe transferir el cliente en el siguiente paso
  • displayName: ID de correo electrónico recuperado del perfil del usuario
  • method: lista de métodos que se están inscribiendo en el método EMAIL
  • factorId: identificador único generado para el factor que se está inscribiendo

Correcto indica que:

  • El valor userGUID o userOcid proporcionado es válido
  • El usuario está activo
  • No se ha bloqueado la cuenta de usuario.
  • El factor EMAIL está activado

Paso 2: Activar el factor EMAIL

Este paso activa la inscripción por correo electrónico para el usuario, en una solicitud PATCH al punto final /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

El cliente debe incluir los siguientes atributos:

  • otpCode: el código recibido por el usuario en su ID de correo electrónico
  • requestState: recibido en la respuesta del paso 1

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido de la solicitud PATCH en formato JSON: 

{
"otpCode":"710130", 
"requestState": "{{requestState}}"
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta con formato JSON: 

{"status":"success"}

Correcto indica que:

  • OTP es válido
  • El valor userGUID o userOcid proporcionado es válido
  • El usuario está activo
  • No se ha bloqueado la cuenta de usuario.
  • El factor EMAIL está activado y el factor se ha inscrito correctamente

Ejemplos de Respuesta de Error

En el siguiente ejemplo se muestra el mensaje de error en formato JSON cuando userGUID no es válido. Obtiene un código de respuesta HTTP 404 si userGUID o userOcid no son válidos.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

El siguiente ejemplo muestra el mensaje de error en formato JSON cuando se desactiva EMAIL. Obtiene un código de respuesta HTTP 401.

{
    "status": "failed",
    "ecId": "0000M00000A",
    "cause": [
        {
            "code": "AUTH-1125",
            "message": "The EMAIL factor has been disabled."
        }
    ]
}