Authentication Factor Enrollment With Factor Verification - SMS

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-enrollment-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:

• Step 1: Initiate SMS Factor Enrollment

• Step 1a: Resend the OTP

• Step 2: Activating the SMS Factor

Note:

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

Step 1: Initiate SMS Factor Enrollment

This step initiates SMS enrollment. The client must include the following attributes:

• method: defines to enroll in SMS factor
• phoneNumber: defines the phone number where the SMS text will be sent
• countryCode: defines the country code of the phone number where the SMS text will be sent

Request Example

The following example shows the POST request to the {{HOST}}/mfa/v1/users/{{userGUID}}/factors endpoint in JSON format :

{ 
"method": "SMS",
"countryCode": "+44", 
"mobileNumber": "1122334455", 
} 

Response Example

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

{
"status": "success", 
"factorId": "88178d80636a428393a5674ba46dc867",
"factorStatus": "ENROLLMENT_INITIATED", 
"methods": [ "SMS" ],
"displayName": "[phone]", 
"requestState": "QK1.....y+OFP//0" 
}

displayName is the mobile number. An otpCode will be sent to the users mobile device, which is used to complete the enrollment.

Step 1a: Resend the OTP

If the user doesn't receive the OTP, this example shows how to request that an OTP be resent. The client must include the following attributes:

requestState: received in the Step 1 response

resendOtp: boolean to indicate that the OTP is received

Request Example

The following example shows the PATCH request to the {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} endpoint in JSON format:

{
 "resendOtp":true,
 "requestState": "QK1.....y+OFP//0"
}

Response Example

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

{ 
"status": "success",
"factorId": "88178d80636a428393a5674ba46dc867", 
"factorStatus": "ENROLLMENT_INITIATED",
"methods": [ "SMS" ],
"displayName": "[phone]",
"requestState": "+HFVV...qgMUI" 
} 

The response contains the following parameters:

• requestState: that should be passed by the client in the next step
• displayName: is the mobile number being enrolled
• method: SMS factor method
• factorId: unique identifier generated for the factor being enrolled

Success indicates that:

• The userGUID that was provided is valid
• The user is active
• The user account isn't locked
• The SMS factor is enabled

Step 2: Activating the SMS Factor

This step activates the SMS enrollment for the user, in a PATCH request to the /mfa/v1/users/{{userGUID}}/factors/{{factorID}}endpoint.

The client must include the following attributes:

• otpCode: the code received by the user on their device
• requestState: 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:

• OTP is valid
• The userGUID that was provided is valid
• The user is active
• The user account isn't locked
• The SMS factor is enabled and factor is enrolled successfully

Error Response Examples

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

{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

The following example shows the error message in JSON format when the user is locked. You get a 401 HTTP response code.

{
 "status": "failed",
 "ecId": "0ISDCif1Qy6wg0000A8",
 "cause": [
 {
 "code": "AUTH-1010",
 "message": "Your account is locked.Contact your system administrator."
 }
 ]
}