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.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": "user1@example.com",
"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 stepdisplayName:
email id of the user enrolledmethod:
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 responseresendOtp:
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": "username@example.com",
"requestState": "AmgsMN.....2sk4SI"
}
The response contains:
requestState
: that should be passed by the client in the next stepdisplayName
: email id fetched from the user's profilemethod
: the list of method(s) being enrolled in EMAIL methodfactorId
: 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
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."
}
]
}