Initiate and Verify a Backup Factor

This use case provides a step-by-step example of using the Oracle Identity Cloud Service Verification API to complete factor verification of the backup 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-factor-verification-api folder within GitHub and then import them into Postman.

There are two steps in this use case:

• Step 1: Initiate and Verify the Backup Factor Security Questions

• Step 2: Initiate and Verify Backup Factor EMAIL

Note:

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

Step 1: Initiate and Verify the Backup Factor Security Questions

This step initiates the verification of a user's backup factor. The client must provide both the factorId and the method in the request. 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 Joe John.

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

To obtain a list of enrolled factors and their IDs for a user, see the Fetch Enrolled Factors of a User Use Case. In this example, the backup factor chosen is Security Questions.

Request Example to Initiate Backup Factor Security Questions

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

Note:

The preferred factorId contains the unique ID of the preferred factor. In case of SECURITY_QUESTIONS, it will have the fixed string "SecurityQuestions".

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

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 requestState contains contextual data needed to process the request.

Response Example

The following example shows the contents of the response in JSON format for backup method 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?"
        }
    ]
}

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 requestState contains contextual data needed to process the request. In this example, a question is sent back from the list of enrolled questions to which the user needs to answer.

Request Example to Verify Backup Factor Security Questions

This step verifies the backup factor by passing the answer to the Security Question in a PATCH request to {{HOST}}/mfa/v1/requests/{{requestID}}.The client must include the following attributes:

• requestState: received in the Step 1 response
• securityQuestions id/answers: defined by the user during enrollment

Request Example

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

{
 "securityQuestions":[
        {
            "id":"MaidenName",
            "answer":"Smith"
        }
    ],
"requestState": "{{requestState}}"
 }
 

Response Example

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

{"status":"success"} 

Success indicates that verification was successful.

Step 2: Initiate and Verify Backup Factor EMAIL

This step initiates the verification of a backup factor EMAIL.

Request Example to Initiate EMAIL factor

The following example shows the request example in JSON format for preferred method "EMAIL"

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

Response Example

The following example shows the response example to initiate EMAIL factor in JSON format:

{ 
 "status":"success",
 "requestId":"<Request ID>",
 "userGUID":"<User GUID>",
 "factorId":"factorID",
 "method":"EMAIL",
 "displayName":"Joe John",
 "requestState":"QYV81R9eoagwWQ"
 }

Request Example to Verify EMAIL Factor

The following example shows the PATCH request in JSON format for EMAIL factor:

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

Response Example

The following example shows the contents of the response in JSON format to verify EMAIL Factor:

{"status":"success"} 

Success indicates that verification was successful.