REST API for Oracle Identity Cloud Service

Using Self Service to Enroll in MFA using the SMS Factor

This use case provides a step-by-step example of using the REST API for Oracle Identity Cloud Service for Self-Service enrollment in Multi-Factor Authentication (MFA) using SMS Factor.

Note:

See the Oracle Identity Cloud Service Authentication API Postman collection for extensive authentication use case examples. Download the collection and the global variables file from the idcs-rest-clients folder within GitHub and then import them into Postman.

As a prerequisite step, you must obtain a ME token before following these steps. See Generating Access Token Using Authentication API for information on obtaining a ME token.

There are three steps in this use case. Each step contains request and response examples:

Note:

These steps assume that relevant factors of MFA are enabled using Configure Multi-Factor Authentication Settings .

Step1: Create the Self Service Enrollment Using the SMS Factor

This step initiates SMS enrollment in a POST request to the /admin/v1/MyAuthenticationFactorEnroller endpoint. The client must include the following attributes:

value: defines the user id. You can make a GET call to {{HOST}}/admin/v1/Me to get the "id" value.
displayName: defines the display name for the device
countryCode: defines the country code of the phone number where the SMS text will be sent
phoneNumber: defines the phone number where the SMS text will be sent

Request Example

The following example shows the contents of the POST request body in JSON format :

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

Response Example

The following example shows the contents of the response body in JSON format:

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

In the response, the deviceId and the requestId should be passed in the next step.

Error Response Examples

The following example shows the error message in JSON format when the userId is invalid. You get a 400 HTTP response code.

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

The following example shows the error message in JSON format if a phoneNumber is incorrect. You get a 400 HTTP response code.

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

Step 2: Initiate the Self Service Enrollment Using the OTP by SMS

This step requests the OTP be sent through SMS in a POST request to the/admin/v1/MyAuthenticationFactorInitiator endpoint. The client must include the following attributes:

requestId: received in the Step 1 response

deviceId: received in the Step 1 response

userName: user name of the user

Request Example

The following example shows the contents of the POST request body in JSON format:

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

Response Example

The following example shows the contents of the response in JSON format:

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

An OTP code is sent via SMS to the user's mobile device. In the response deviceId and requestId should be passed in the next step.

2a. Initiate the Self Service Enrollment Request to Resend OTP by SMS

In case the user wants the server to "resend" the OTP, then same payload as mentioned in the Step 2 should be sent to the server again.

Request Example

The following example shows the contents of the POST request body in JSON format:

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

Response Example

The following example shows the contents of the response in JSON format:

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

An OTP code is sent via SMS to the user's mobile device. In the response deviceId and requestId should be passed in the next step.

Step 3: Validate the Self Service Enrollment Using the OTP

This step validates the SMS enrollment of a user in a POST request to the /admin/v1/MyAuthenticationFactorValidator endpoint.

The client must include the following attributes:

otpCode: the code received by the user on their device
requestId: received in the Step 2 response
deviceId: received in the Step 2 response

Request Example

The following example shows the contents of the POST request in JSON format:

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

Response Example

The following example shows the contents of the response in JSON format:

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

In the response, the attribute mfaStaus:"ENROLLED" indicates that user has enrolled for MFA. The preferredAuthenticationFactor attribute indicates the factor set as the preferred method. In this case, it is SMS.

Error Response Examples

The following example shows the error message in JSON format if OTP is incorrect. You get a 401 HTTP response code and the enrollment fails.

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