Documentación de Oracle Cloud Infrastructure

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

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

Nota

Utilice esta API de autenticación solo si está creando su propia experiencia de conexión completa mediante el desarrollo de una aplicación de conexión personalizada para que los dominios de identidad la utilicen.
Nota

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

La API de MFA de On Demand se basa en el concepto de máquina de estado. Las respuestas de solicitud informan a un cliente de aplicación lo que debe hacer a continuación en lugar de exigir a los usuarios que tengan activadas 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 permitidas.

La API de MFA de On Demand puede:
  • Soporta la inscripción de usuarios con factores de MFA activados por el administrador
  • Reforzar la seguridad de la autenticación basada en contraseña mediante la autenticación multifactor (MFA) mediante la necesidad de 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.
  • Realizar inscripciones en MFA, verificación de MFA y gestión de factor de autenticación de usuarios.

En este caso de uso se incluyen los siguientes juegos de ejemplos:

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 se ha inscrito un usuario.

En estos pasos, se asume que los factores relevantes de la 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 desde 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. Vd. puede solicitar tanto userGUID como 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 el nombre de usuario o userGUID.

Ejemplo de solicitud 

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

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido de la respuesta en 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 userGUID, el factor preferido y el factor inscrito.

Paso 2: Obtener Factores Inscritos para un Usuario mediante Filtros

Puede obtener los factores inscritos 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 según 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 en 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 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 en 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 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 de 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 la 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 desde 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 desde la carpeta idcs-factor-verification-api en GitHub y, a continuación, impórtelos en Postman.

Utilice 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. Vd. puede solicitar tanto userGUID como 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 userId. userIdType en la solicitud indica qué tipo de credencial está transfiriendo el usuario 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 transferida.

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 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 de factores. 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 en formato JSON: 

{"status":"success"}

El éxito indica que la verificación se realizó correctamente.

Iniciar y verificar un factor de copia de seguridad

Este caso de uso proporciona un ejemplo paso a paso 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 la 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 desde la carpeta idcs-factor-verification-api en el repositorio idm-samples GitHub y, a continuación, impórtelos en Postman.

Utilice 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. Vd. puede solicitar tanto userGUID como userOcid en sus solicitudes.

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

Este paso inicia la verificación del factor de copia de seguridad de un usuario. El cliente debe proporcionar tanto factorId como 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 userId. userIdType en la solicitud indica qué tipo de credencial está transfiriendo el usuario 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 transferida.

Para obtener una lista de los factores inscritos y sus ID para un usuario, consulte el caso de uso Fetch Enrolled Factors of a User. En este ejemplo, el factor de copia de seguridad elegido es Preguntas de seguridad.

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 a {{HOST}}/mfa/v1/requests/endpoint en formato JSON:

Nota

El 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 de factores. requestState contiene los 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 de factores. requestState contiene los 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 en formato JSON: 

{"status":"success"}

El éxito indica que la verificación se realizó correctamente.

Paso 2: Iniciar y verificar EMAIL de factor de copia de seguridad

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

Ejemplo de solicitud para iniciar el factor EMAIL

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

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

Ejemplo de respuesta

El siguiente ejemplo muestra el ejemplo de respuesta para iniciar el factor EMAIL en 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

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

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

Ejemplo de respuesta

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

{"status":"success"}

El éxito 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 (SMS, 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 desde 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 la MFA se activan mediante Configurar valores de autenticación multifactor.

Carga Útil de Solicitud
Atributo Valores soportados/valores de muestra Varios valores Detalles de Uso
userFlowControlledByExternalClient true / false falso
Defina 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 al mismo mediante el atributo x5t en el ejemplo de solicitud, como se menciona a continuación.
x5t Cadena / X509 Huella digital 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 Varios valores Detalles de Uso
otp

Mapa

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

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 digital 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 de 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 la 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 desde la carpeta idcs-factor-enrollment-api en el repositorio idm-samples GitHub y, luego, impórtelos en Postman.

Utilice 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. Vd. puede solicitar tanto userGUID como userOcid en sus solicitudes.

Paso 1: Iniciar inscripción en 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 en 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á un mensaje 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 en 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
El éxito indica que:
  • El userGUID proporcionado es válido
  • El usuario está activo
  • La cuenta de usuario no está bloqueada
  • El factor SMS está activado

Paso 2: Activación del factor SMS

Este paso activa la inscripción por 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 en formato JSON: 

{"status":"success"}

El éxito indica que:

  • OTP es válido
  • El userGUID proporcionado es válido
  • El usuario está activo
  • La cuenta de usuario no está bloqueada
  • El factor SMS está activado y el factor se ha inscrito correctamente

Ejemplos de respuesta a errores

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 de 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 la 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 desde la carpeta idcs-factor-enrollment-api en el repositorio idm-samples GitHub y, luego, impórtelos en Postman.

Utilice 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. Vd. puede solicitar tanto userGUID como userOcid en sus solicitudes.

Paso 1: Iniciar inscripción en 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 en formato JSON: 

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

Se enviará un 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
  • ID de correo electrónico displayName: del usuario inscrito
  • method: Método de factor de correo electrónico

El éxito indica que:

Se inició la inscripción de factores.

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 ha recibido 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 en formato JSON: 

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

La respuesta contiene:

  • requestState: el cliente debe transferirlo 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 inscribe

El éxito indica que:

  • El valor userGUID o userOcid proporcionado es válido
  • El usuario está activo
  • La cuenta de usuario no está bloqueada
  • 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 de PATCH para el 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 en formato JSON: 

{"status":"success"}

El éxito indica que:

  • OTP es válido
  • El valor userGUID o userOcid proporcionado es válido
  • El usuario está activo
  • La cuenta de usuario no está bloqueada
  • El factor EMAIL está activado y el factor se ha inscrito correctamente

Ejemplos de respuesta a errores

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."
        }
    ]
}

En el siguiente ejemplo, se 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."
        }
    ]
}