OneSpan Developer: Intelligent Adaptive Authentication - User Registration

Hakim Aldaoub, July 8, 2020
Intelligent Adaptive Authentication

OneSpan Intelligent Adaptive Authentication (IAA) provides a user registration REST API for the Sandbox environment to let you smoothly integrate the user registration functionality within your web or mobile application. In this article, we will explore the user registration API which resides in the OneSpan IAA Interactive Sandbox API. Check out our previous blog “Intelligent Adaptive Authentication Sandbox API Intro” for an introduction of the IAA Sandbox API. 

Before We Begin

Prior to exploring the user registration API, you must first be a OneSpan Community member and sign up for a free Intelligent Adaptive Authentication sandbox account. Check out our previous blog ”OneSpan Cloud Solutions In Action - MyBank Web Portal Demo, Part 1” for instructions on how to do so.

Introduction

The user registration API allows you to provision a new user account for OneSpan Intelligent Adaptive Authentication  and automatically assign an authenticator to that newly created user account. Provisioning a user instance on the OneSpan Risk Analytics is essential for leveraging the IAA comprehensive activities. 

Navigate to the User Registration Interactive API

In order to experiment with the user registration API, navigate to the IAA Sandbox Interactive API of your OneSpan Community account. In the Open API Swagger editor, expand the “Provisioning” resource. You will then find an entry for the user registration HTTP Post method as in the image below. 

July8th20_1

 

Example of the Structure of the User Registration API URL

The request URL for this API call will resemble the one below

https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/users/register

You won’t need to provide this URL during the tutorial. It is only for reference. The URL will be automatically assigned in the Interactive API when calling the web service. 

User Registration API Request Body

Under the “Request Body” section of User Register endpoint, select "AdaptiveRegisterUserInput" object type from the dropped down menu as shown below. This object type is used to create a new user for the purpose of IAA activities. You will then get an example of the JSON payload for the registration request. It will be populated with the JSON objects, which are required by the API of the "AdaptiveRegisterUserInput" object type. 

July8th20_02

The request body will look like the example below of the “users/register” endpoint’s required fields.

Request Payload

{

  "objectType": "AdaptiveRegisterUserInput",

  "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"

                   }

           },

  "clientIP": "192.168.0.1",

  "relationshipRef": "userid1",

  "staticPassword": "Test1234",

  "sessionID": "4ED23EA44F23",

  "userID": "userid1"

}

 

Request Payload’s Required Fields’ Description

 JSON Required Data Fields Description     Fields Data Type
cddc* 

Client Device Data Collector meta data. The two fields browserCDDC and mobileCDDC are mutually exclusive and collectively exhaustive

Type: string
Example: “browserCDDC” or “mobileCDDC”
relationshipRef*     The Relationship reference of the user ID

Type: string
MinLength: 1
MaxLength: 150
Example: iaa_user

staticPassword* The initial static password assigned to the user. 

Type: string
minLength: 8
maxLength: 255
example: Test1234

sessionID*   Application session identifier formatted as a hexadecimal string; common for all transactions related to the same session.

Type: string
pattern: ^[0-9a-fA-F]+$
minLength: 2
maxLength: 100
example: 4ed23ea44f23

userID* A unique identifier for the user to be registered in the system.

Type: string
minLength: 1
maxLength: 255
example: iaa_user

Calling the User Registration Endpoint

It is now time to send the request and register the user for OneSpan IAA. To make the API call, click on the “Try it out” button shown in the screenshot below, on the right side of the “/users/register” Post method section. Once requested, you will receive the response body back in a JSON format. It will be similar to the response payload described in the following section.

July8th20_3a
 

User Registration API Call Response Body:

Below is an example of returned response body of the “/users/register” API call.



  {

    "activationPassword": "xK384IF4",

    "serialNumber": "VDS0064137",

    "riskResponseCode": 0

  }


Response Payload Fields Description

activationPassword: The activation password that will be used later to activate the authenticator on the end user trusted device

serialNumber: The serial number of the authenticator which is automatically assigned to the new user instance

riskResponseCode: The response code that is specific and returned OneSpan Risk Analytics

Once the registration process is completed, you will receive a response body similar to the example above and with a 200 response code which indicates the successful registration of a new user for the IAA Sandbox environment.

In this blog, we described how to register a new user using the IAA Sandbox Interactive API. We have also explored the structure and seen examples of the request and the response payloads, which are required by the “/users/register” endpoint. If you have any questions regarding this tutorial, feel free to reach us on the OneSpan Community Portal Forums. 

OneSpan Developer Community

OneSpan Developer Community

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

Join Today