Orchestration SDK: Local Authentication with Challenge/Response – Part 1

Orchestration SDK is an integral part of OneSpan Mobile Security Suite, which enables mobile developers to integrate the OneSpan Cloud Authentication (OCA) and Intelligent Adaptive Authentication (IAA) use cases to their mobile application with a minimum effort.

In this blog, we will demonstrate you how to authenticate an end-user via Challenge/Response using a customer mobile application integrated with Orchestration SDK. Without further delay, let’s get started!

Prerequisites

-Register a OneSpan Intelligent Adaptive Authentication Sandbox Tenant.
-A mobile phone with Android 4.1 or later, with installed Orchestration SDK sample app.
-Register an end-user and activate the Trusted Device.

Integration of the End-user Login with Challenge/Response

The main flow of Challenge/Response authentication starts when a customer web application requests a challenge from OneSpan’s authentication service and presents it to the end-user on a login page.
From there, the user enters it in their authenticator and generates a response offline (in our case, we will demonstrate with a mobile app integrated with Orchestration SDK).

The user will then enter the response into the customer web application, which is validated by OneSpan Cloud Authentication (and potentially OneSpan Risk Analytics). When the validation is successful, authentication is complete and the customer web application can log the user in.

STEP 1: Issue a “Generate Challenge” Request

The end-user initiates the login operation. This triggers the client application to send the below API request to generate a challenge:

HTTP Request

POST https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userid@domain}/generate-challenge

HTTP Headers

Accept: application/json

Example Payload ​​​​

{
  "length": 6,
  "checkDigit": false
}

-length is a number from minimum 4 to maximum 16. The standard Challenge/Response (CR) application in a Digipass® authenticator normally accepts 6 digits.
-checkDigit: Possible values are true or false.

Example Response

{
  "requestID": "39d468d1-7209-4572-88ef-6cbc0f87abd3",
  "challenge": "324067"
}

-requestID: The client application needs to cache this request ID and uses it in a later call.

Once the API returns successfully, the client application should present the challenge to the end-user and provide an input field awaiting the response.

STEP2: Generate an OTP on the Trusted Device

In order to generate a response accordingly, the end-user will need the Orchestration sample app installed on their mobile and will need to activate the mobile as their trusted device. This flow is offline for the authenticator, therefore you can turn on airplane mode during the test. Once that’s done, click the “TRY IT” button under the Local Authentication section:

On the local authentication page, enter the response and select any of the out-of-the-box protection types (e.g.,biometric). You will be prompted for fingerprint verification before generating a response.

STEP3: Issue a Login Request

The end-user fills the response in the client application and triggers the client application to send another API request to validate the Challenge/Response against the OneSpan authentication service:

HTTP Request

POST https://{tenant}.{environment}.tid.onespan.cloud/v1/users/{userid@domain}/login

HTTP Headers

Content-Type: application/json
Accept: application/json

If you are only leveraging the OneSpan Cloud Authentication solution, use the payload below and OneSpan Cloud Authentication will validate the Challenge/Response OTP and return the validation result:

Example Payload

{
  "objectType": "LoginInput",
  "credentials": {
    "authenticator": {
      "OTP": "177391"    
    }
  },
  "requestID": "39d468d1-7209-4572-88ef-6cbc0f87abd3"
}

Example Respons{

{

  "sessionStatus": "success"

}

If you are also using the OneSpan Risk Analytics solution to perform continuous fraud monitoring and dynamic risk assessment, use this payload instead:

Example Payload

{
  "objectType": "AdaptiveLoginInput",
  "cddc": {
    "browserCDDC": {
      "fingerprintRaw": "{browser:{\"userAgent\":Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36},support:{\"ajax\":true,\"boxModel\":undefined,\"changeBubbles\":undefined,\"checkClone\":true,\"checkOn\":true,\"cors\":true,\"cssFloat\":undefined,\"hrefNormalized\":undefined,\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,\"noCloneChecked\":true,\"noCloneEvent\":undefined,\"opacity\":undefined,\"optDisabled\":undefined,\"style\":undefined,\"submitBubbles\":undefined,\"tbody\":undefined},computer:{\"screenWidth\":2560,\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",\"platform\":\"Win32\"},additional:{}}",
      "fingerprintHash": "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7"
    }
  },
  "relationshipRef": "ala_user03",
  "sessionID": "4ED23EA44F23",
  "clientIP": "192.168.0.1",
  "credentials": {
    "authenticator": {
      "OTP": "177391"
    }
  },
  "requestID": "39d468d1-7209-4572-88ef-6cbc0f87abd3"
}

Example Response

{
   "riskResponseCode": 0,

  "sessionStatus": "success"

}

Note:
Include the same request ID derived from the generate-challenge request and the response created from that challenge.

After the OneSpan authentication service validates the Challenge/Response and returns the validation result: If the “sessionStatus” attribute in the response JSON is “success”, the authentication has been successful and the client application can securely log the end-user in.

There it is. Through today’s blog, you should have enough knowledge to design a Challenge/Response local authentication workflow.

In next blog, we will walk you through the Orchestration SDK programming for this workflow so that you can integrate the SDK into your existing mobile application.

If you have any questions regarding this blog or anything else concerning the integration of OneSpan Cloud Authentication or Intelligent Adaptive Authentication into your application, visit the Developer Community Forums. Your feedback matters to us!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today