Initiate and Verify the Preferred Factor

This use case provides a step-by-step example of using the Oracle Identity Cloud Service Factor Enrollment API to enroll for Multi-Factor Authentication (MFA) with Factor Verification.

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-factor-verification-api folder within GitHub and then import them into Postman.

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

• Step1: Initiate Verification of the Preferred Factor

• Step 2: Verify the Preferred Factor

Note:

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

Step1: Initiate Verification of the Preferred Factor

This step initiates the verification of a user's preferred factor. If you need to use the verify factor API without providing the userGUID, you can provide a user unique id such as user name as the userId. The userIdType in the request indicates what type of credential the user is passing as the value for the userId. The following userIdType values are accepted:

• USER_GUID - For example, here userId should contain USER_GUID such as "7b3d902ab05b4214"
• USER_NAME - For example, here userId should contain USER_NAME such as John.

The userId attribute contains the actual value of the user credential that is passed.

Request Example

The following example shows the POST request to {{HOST}}/mfa/v1/requests endpoint in JSON format.

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

Response Example

The following example shows the contents of the POST response to {{HOST}}/mfa/v1/requests endpoint in JSON format after initiating preferred factor on the preferred ID :

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

In the response, the requestId value is the unique identifier generated for this request. Include the requestId in every subsequent call to complete factor verification. The factorId is the preferred device on which it was initiated. The method is the factor that the user has initiated. The requestStatecontains the contextual data needed to process the request.

In this example, an otpCode(in case of SMS and EMAIL factor) is sent via SMS to the user's mobile device.

Step 2: Verify the Preferred Factor

This step verifies the factor by passing the otpCode in a PATCH request to {{HOST}}/mfa/v1/requests/{{requestId}}.

The client must include the following attributes:

• otpCode: the code received by the user on their device
• requestState: received in the Step 1 response
• requestId: received in the Step 1 response

Request Example

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

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

Response Example

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

{"status":"success"} 

Success indicates that verification was successful.