Documentación de Oracle Cloud Infrastructure

Inscripción en MFA mediante el 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 factor de 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, debe obtener un token de 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 de ME.

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

En estos pasos se asume que los factores relevantes de la MFA se activan 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 del 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 solicitud POST con 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 con 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, se deben transferir deviceId y requestId en el siguiente paso.

Ejemplos de Respuesta de Error

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

El ejemplo siguiente 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: Inicio de 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

userName: nombre de usuario

Ejemplo de solicitud

En el siguiente ejemplo se muestra el contenido del cuerpo de solicitud POST con 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 con 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, se deben transferir deviceId y requestId 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 solicitud POST con 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 con 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, se deben transferir deviceId y requestId en el siguiente paso.

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

Este paso valida la inscripción de 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 con 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 con 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 en MFA. El atributo mfapreferredAuthenticationFactor indica el juego de factores como método preferido. En este caso, es SMS.
Nota

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

Ejemplos de Respuesta de Error

El ejemplo siguiente 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"
  }
}