1. REST API for Oracle Identity Cloud Service
  2. Tasks
  3. On-Demand MFA
  4. Factor Verification

Complete Factor Verification

patch

/mfa/v1/requests/{requestId}

Request

Supported Media Types
Path Parameters
  • Unique identifier of a factor authentication request returned by the server, when the user initiated factor verification
Header Parameters
  • Provide a valid OAuth Access Token that has either the 'Authenticator Client' or 'MFA Client' scope.
Body ()
Complete Factor Verification Schema
Root Schema : CompleteFactorVerification
Type: object
Use this schema to complete factor verification or to resend OTP
Show Source
  • This attribute indicates the pre-generated bypass code that the user wants to use, while authenticating using BYPASSCODE method.
  • This attribute provides the one time passcode that the user received over SMS, PHONE_CALL, EMAIL or the TOTP that was generated by the Oracle Mobile Authenticator App enrolled in IDCS. This attribute is only applicable for TOTP, SMS, PHONE_CALL and EMAIL methods.
  • This contains the context/request related details in encrypted form, which needs to be passed back and forth between server and client. The details are needed by the server to process a request and are opaque to the client.
  • Attribute to indicate if the user wants the OTP to be resent to the mobile number or email id being used to authenticate. Supported values for this attribute are:
    • true
    • false
    This attribute is considered only for EMAIL, PHONE_CALL and SMS factors.
  • securityQuestions
    List of Security Questions being used for verification
Nested Schema : securityQuestions
Type: array
List of Security Questions being used for verification
Show Source
Nested Schema : SecQuesVerification
Type: object
Use this schema to complete Security Questions factor verification
Show Source
  • Answer to an enrolled security question that the user wants to use for authentication.
  • The identifier of an enrolled security question that is being used for authentication by a user.
Back to Top

Response

200 Response

Indicates successful authentication.

400 Response

Indicates that the request payload is invalid.

401 Response

Indicates unsuccessful authentication if the otpCode/security answer provided was invalid. Indicates unauthorized access if the token provided is invalid or if the user is either locked, inactive, or not enrolled in MFA.

404 Response

Indicates that the requestId provided is invalid.

500 Response

Internal Server error
Back to Top

Examples

The following example shows how to complete verification of a preferred factor or a backup factor by submitting a PATCH request on the REST resource using cURL. For more information about cURL, see Use cURL.

This method can also be used to request that the time-based one-time passcode (TOTP) be resent when the SMS or EMAIL factors are used.

Factor verification is a 2-step process. You first need to ask Oracle Identity Cloud Service to "initiate" the verification of the factor (for example, send an SMS with a time-based one-time passcode (TOTP), send an email with a TOTP code, or send a PUSH notification to the enrolled Oracle Mobile Authenticator (OMA) app). Use the POST method for this endpoint to initiate the verification.

After initiating, the client needs to "verify" the factor by passing the otpCode, security answer, accepting a PUSH notification on the OMA app, or using a bypass code.

Note:

There is an Oracle Identity Cloud Service Factor Verification Postman collection available. Download the collection and example environment with variables from the idcs-factor-verification-api folder within GitHub and import them into a REST client.

Note:

The command in this example uses the URL structure https://tenant-base-url/resource-path, where tenant-base-url represents the Identity Service URL, and the resource path represents the Identity Service API. See Send Requests for the appropriate URL structure to use.

The following request and response examples are included for this API:

curl
-X PATCH
-H "Content-Type:application/scim+json"
-H "Authorization: Bearer <Access Token Value>"
https://tenant-base-url/mfa/v1/requests/<requestId>

Example of a Request Body When Verifying the Preferred SMS/EMAIL/TOTP Factors

Verify the factor by passing the otpCode and the requestState from the initiate verification response (see initiate verification examples on the POST method page for this endpoint), or by accepting the PUSH notification on the OMA app. The following example shows the contents of the request body in JSON format when verifying an SMS/EMAIL/TOTP factor: 

{
    "otpCode": "629084",
    "requestState": "{{requestState}}"
}

Example of a Request Body When Verifying the Security Question Factor

The following example shows the contents of the request body in JSON format when verifying a Security Question factor:

{
    "securityQuestions": [
        {
            "id": "FirstCar",
            "answer": "Ford Pinto"
        }
    ],
    "requestState": "{{requestState}}"
}

Example of a Request Body Verifying the Bypass Code Factor

The following example shows the contents of the request body in JSON format verifying the Bypass Code factor:

{
    "bypassCode": "397541940949",
    "requestState": "{{requestState}}"
}

Example of a Response Body When Verifying Factors

The following example shows the contents of the response body in JSON format when verifying factors:

{
    "status": "success"
}

The following example shows the contents of the response body in JSON format when the verification fails. The cause attribute is included that contains the error code and the error message: 

{
    "status": "failed",
    "cause": [
        {
            "message": "Invalid passcode.",
            "code": "AUTH-1105"
        }
    ]
}
{  
    "status": "failed",
    "ecId": "0000MGIHrvfF8DKpISDCif1R9rrp00000G",
    "cause": [  
        {  
            "code": "AUTH-1111",
            "message": "You entered invalid answer(s). Authentication failed."
        }
    ]
}

Example of a Request Body When Requesting That a OTP Be Resent

If the factor is SMS/EMAIL and the user hasn't received the OTP, the client can request that the server to send it again. Every SMS/EMAIL sent increments the user's MFA login attempt count. After the user meets their maximum login attempts, the user account is locked if the user doesn't make a successful login after requesting the OTP. The following example shows the contents of the request body in JSON format when requesting that a OTP be resent. The requestState is obtained from the initiate verification response (see initiate verification examples on the POST method page for this endpoint): 

{
    "resendOtp": true,
    "requestState": "{{requestState}}"
}

Example of a Response Body When Requesting That a OTP Be Resent

The following example shows the contents of the response body in JSON format when requesting that a TOTP be resent. The response contains the requestID and the requestState needed for the next request: 

{
    "status": "success",
    "requestId": "e2746358-a077-41f8-8c16-269b61f3bd87",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "30db2274140043918edb033d9fe29ff3",
    "method": "EMAIL",
    "displayName": "user1@example.com",
    "requestState": "fMDFvx.....0Rf/CUY"
}
Back to Top