Authentication Factor Enrollment With Factor Verification - Email

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 Email Factor Enrollment

• Step 1a: Resend the OTP

• Step 2: Activate the EMAIL Factor

Note:

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

Step 1: Initiate Email Factor Enrollment

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

• method: defines to enroll in Email. User will not pass the email id. The primary email id is automatically fetched from the user's profile.

Request Example

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

{ 
"method": "EMAIL",
} 

Response Example

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

{
"status": "success",    
"factorId": "30db2274140043918edb033d9fe29ff3",
"factorStatus": "ENROLLMENT_INITIATED",  
"methods": ["EMAIL"],
"displayName": "[e-mail]", 
"requestState": "Vxar...bWTTA"
    }

An otpCode will be sent to the user's email id, which is used to complete the enrollment.

The response contains:

• requestState: that should be passed by the client in the next step
• displayName: email id of the user enrolled
• method: EMAIL factor method

Success indicates that:

The factor enrollment was initiated.

Step 1a: Resend the OTP

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

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: to indicate that the OTP is recieved

Request Example

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

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

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

{    
"status": "success",     
"factorId": "30db2274140043918edb033d9fe29ff3",
"factorStatus": "ENROLLMENT_INITIATED",   
"methods": ["EMAIL"],
"displayName": "[e-mail]", 
"requestState": "AmgsMN.....2sk4SI" 
}
    

The response contains:

• requestState: that should be passed by the client in the next step
• displayName : email id fetched from the user's profile
• method: the list of method(s) being enrolled in EMAIL 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 EMAIL factor is enabled

Step 2: Activate the EMAIL Factor

This step activates the EMAIL 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 email id
• requestState: received in the Step 1 response

Request Example

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

{
"otpCode":"710130", 
"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 EMAIL 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 EMAIL is disabled. You get a 401 HTTP response code.

{
    "status": "failed",
    "ecId": "0000M00000A",
    "cause": [
        {
            "code": "AUTH-1125",
            "message": "The EMAIL factor has been disabled."
        }
    ]
}