1. Oracle Identity Cloud Service REST APIREST API for Oracle Identity Cloud Service
  2. Use Cases
  3. Using the On Demand MFA API to Develop Custom Sign-In Page
  4. Factor Enrollment With Verification
  5. Return OTP Factors without Notifying the User

Return OTP Factors without Notifying the User

This use case provides an example of initiating the On Demand MFA API to return one-time passcode (OTP) factors (SMS or Email or Phone Call) in a response without notifying the user.

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.

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

Request Payload
Attribute Supported Values / Sample Values Multi-Valued Usage Details
userFlowControlledByExternalClient true / false false
Set this option to 
true
and the OTP will be returned in the response in the encrypted format specified.

Note: The certificate used for encryption is uploaded to the application in advance and is referred using the x5t attribute in the request example as mentioned below.

x5t String / X509 SHA-1 Certificate Thumbprint  

When specified, the service uses this uploaded certificate to encrypt the OTP data.

Note: The "x5t" attribute should match the uploaded certificate.

Request Example 
{
    "userId":"<Unique Id>",
    "userIdType":"USER_NAME/USER_GUID",
    "userFlowControlledByExternalClient": true,
    "x5t" :"<certificate thumbprint>"
}
Response Payload
Attribute Supported Values / Sample Values Multi-Valued Usage Details
otp

Map

"otp": {
    "value": "IMCw==",
    "alg": "RSAES-OAEP",
      "x5t": "<certificate thumbprint>"
 }
false

When present in the response, the attribute contains the encrypted OTP with following details.

  • value: Encrypted value.
  • alg: Algorithm used for encryption.
  • x5t: SHA-1 X509 Thumbprint of the certificate used for encryption.

Response Example

{
    "status": "success",
    "requestId": "<Request ID>",
    "userGUID": "<User GUID>",
    "factorId": "<SMS/EMAIL/PHONE_CALL factor GUID>",
    "method": "SMS/EMAIL/PHONE_CALL",
    "displayName": "+91XXXXXXXX984",
    "requestState": "4p7ViEzP2bP1MIM",
    "otp": {
        "value": "<Encrypted OTP value>",
        "alg": "<Encryption algorithm>",
        "x5t": "<x5t of the certificate used to encrypt the OTP>"
           }
}