Documentación de Oracle Cloud Infrastructure

Inscripción en MFA mediante factor SMS mediante autoservicio

Este caso de uso proporciona un ejemplo paso a paso del uso de la API de REST de dominios de identidad para la inscripción de autoservicio en la autenticación multifactor (MFA) mediante el uso de factor SMS.

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-rest-clients en el repositorio idm-samples GitHub y, a continuación, impórtelos en Postman.

Como paso de requisito previo, debe obtener un token ME antes de seguir estos pasos. Consulte Generación de token de acceso mediante la API de autenticación para obtener información sobre la obtención de un token ME.

En este caso de uso hay tres pasos. Cada paso contiene ejemplos de solicitud y respuesta:
Nota

En estos pasos se asume que los factores relevantes de la MFA están activados mediante Configurar valores de autenticación multifactor.

Step1: creación de la inscripción de autoservicio mediante el factor SMS

Este paso inicia la inscripción de SMS en una solicitud POST al punto final /admin/v1/MyAuthenticationFactorEnroller. El cliente debe incluir los siguientes atributos:

  • value: define el ID de usuario. Puede realizar una llamada GET a {{HOST}}/admin/v1/Me para obtener el valor "id".
  • displayName: define el nombre mostrado para el dispositivo
  • countryCode: define el código de país del número de teléfono al que se enviará el texto SMS
  • phoneNumber: define el número de teléfono al que se enviará el texto SMS

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido del cuerpo de la solicitud POST en formato JSON: 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
  ],
  "user": {
    "value": "c810ff4522eb437abac013291c1984d1"
  },
  "displayName": "Joe's Personal Phone",
  "countryCode": "+44",
  "phoneNumber": "1122334455",
  "authnFactors": [
    "SMS"
  ]
}

Ejemplo de respuesta

En el siguiente ejemplo se muestra el contenido del cuerpo de respuesta en formato JSON: 

{
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
    ],
    "user": {
        "value": "c810ff4522eb437abac013291c1984d1",
        "$ref": "https://example.identitycloud.com/admin/v1/Users/c810ff4522eb437abac013291c1984d1"
    },
    "displayName": "Joe's Personal Phone",
    "countryCode": "+44",
    "phoneNumber": "XXXXXXX455",
    "authnFactors": [
        "SMS"
    ],
    "meta": {
        "resourceType": "MyAuthenticationFactorEnroller",
        "location": "https://example.identitycloud.com/admin/v1/MyAuthenticationFactorEnroller"
    },
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179"
}

En la respuesta, deviceId y requestId se deben transferir en el siguiente paso.

Ejemplos de respuesta a errores

En el siguiente ejemplo se muestra el mensaje de error en formato JSON cuando userId no es válido. Obtiene un código de respuesta HTTP 400. 
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error",
        "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
    ],
    "detail": "AuthenticationFactorEnroller.user references a User with ID 1fa35f74491d44ef5a7cc25bfdb1c8b1c that does not exist.",
    "status": "400",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
        "messageId": "error.common.validation.invalidReferenceResource"
    }
}

En el siguiente ejemplo se muestra el mensaje de error en formato JSON si phoneNumber es incorrecto. Obtiene un código de respuesta HTTP 400.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error",
        "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
    ],
    "detail": "Your phone number +91123 is not valid.",
    "status": "400",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
        "messageId": "error.ssocommon.auth.invalidPhoneNumber",
        "additionalData": {
            "params": "+91123",
            "msgId": "error.ssocommon.auth.invalidPhoneNumber"
        }
    }
}

Paso 2: Iniciar la inscripción de autoservicio mediante OTP por SMS

Este paso solicita que la OTP se envíe a través de SMS en una solicitud POST al punto final /admin/v1/MyAuthenticationFactorInitiator. El cliente debe incluir los siguientes atributos:

requestId: recibido en la respuesta del paso 1

deviceId: recibido en la respuesta del paso 1

Nombre de usuario userName: del usuario

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido del cuerpo de la solicitud POST en formato JSON:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "userName": "jbloggs",
  "authFactor": "SMS"
}

Ejemplo de respuesta

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

{
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "authFactor": "SMS",
    "userName": "jbloggs",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ]
}

Un código OTP se envía mediante SMS al dispositivo móvil del usuario. En la respuesta, deviceId y requestId se deben transferir en el siguiente paso.

2a. Inicio de la petición de inscripción de autoservicio para reenviar OTP por SMS

En caso de que el usuario desee que el servidor "reenvíe" la OTP, se debe volver a enviar al servidor la misma carga útil que se menciona en el Step 2.

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido del cuerpo de la solicitud POST en formato JSON:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "userName": "jbloggs",
  "authFactor": "SMS"
}

Ejemplo de respuesta

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

{ 
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "authFactor": "SMS",
    "userName": "jbloggs",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ]
}

Se envía un código OTP mediante SMS al dispositivo móvil del usuario. En la respuesta, deviceId y requestId se deben transferir en el siguiente paso.

Paso 3: Validación de la inscripción de autoservicio mediante OTP

Este paso valida la inscripción por SMS de un usuario en una solicitud POST al punto final /admin/v1/MyAuthenticationFactorValidator.

El cliente debe incluir los siguientes atributos:

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

Ejemplo de solicitud

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "otpCode": "191224",
  "authFactor": "SMS",
  "scenario": "ENROLLMENT"
}

Ejemplo de respuesta

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

{
    "authFactor": "SMS",
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "scenario": "ENROLLMENT",
    "status": "SUCCESS",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
    ],
    "mfaStatus": "ENROLLED",
    "mfaPreferredDevice": "2b27b8c072d64b899d41c8470acea32a",
    "mfaPreferredAuthenticationFactor": "SMS",
    "securityQuestionsPresent": false,
    "devicesCount": 3,
    "emailFactorEnrolled": true
}
En la respuesta, el atributo mfaStaus:"ENROLLED" indica que el usuario se ha inscrito para MFA. El atributo mfapreferredAuthenticationFactor indica que el factor definido es el método preferido. En este caso, es SMS.
Nota

Este valor puede ser diferente si el primer factor inscrito es diferente del de SMS.

Ejemplos de respuesta a errores

En el siguiente ejemplo se muestra el mensaje de error en formato JSON si OTP es incorrecto. Obtiene un código de respuesta HTTP 401 y la inscripción falla.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
  ],
  "detail": "Invalid passcode.",
  "status": "401",
  "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
    "messageId": "error.ssocommon.auth.invalidPasscode"
  }
}