OneSpan Developer: Intelligent Adaptive Authentication – Authenticator Assignment Endpoint

Hakim Aldaoub, September 16, 2020
OneSpan Developer: Intelligent Adaptive Authentication – Authenticator Assignment Endpoint

In the previous blog, we demonstrated how to query the authenticators to get a list of the available instances to utilize in a specific domain. Today, we will show how to assign an authenticator for a specific user using the Sandbox Interactive API of the OneSpan Intelligent Adaptive Authentication (IAA). 

Before We Begin

Prior to exploring the Assign Authenticator 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.

You should also be sure to have at least one registered user prior to trying this call. To learn how to register a user, check out OneSpan Developer: Intelligent Adaptive Authentication - User Registration.

Endpoint URL

The request URL for this API call will resemble the example below: https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/authenticators/{serial_Number}/
assign
 

You won’t need to provide this URL during the tutorial. It is only to show the structure of the URL. The URL will be automatically assigned in the Interactive API when calling the webservice. 

Try It Out

In order to experiment with the Authenticator Assignment API, navigate to the IAA Sandbox Interactive API document in your OneSpan Community account. In the Open API Swagger editor, expand the “Authenticators” resource. You will then find an entry for the Authenticators Assignment HTTP Post method as shown in the image below:  

OneSpan-BlogImage-Authenticator-Assignment-Endpoint_1_1

URL Path Parameters:

The only path parameter required for the Assign Authenticator API is the serial number of the authenticator, which we intend to assign for the user specified in the request body. The serialNumber variable is of type string. It is a unique identifier assembled from three letters and seven digits. For example, a serial number could be VDS0066822.

As noticed in the Assign Authenticator URL above, it is required to provide a serial number for the authenticator to be assigned to the user. To do so, we will need to look up the authenticators available in a specific domain, then obtain the serial number of the authenticator in order to assign it to the end user. If you do not know how to do so, we can help! Check out our previous blog, OneSpan Developer: Intelligent Adaptive Authentication - Authenticators Query Endpoint

Assign-Authenticator Request Body

In the Sandbox Interactive API, the request payload of the “Authenticator Assign” endpoint point will resemble the example below:


{

  "domain": " ospanuser-mail",

  "userID": " iaa_user"

}

It contains two mandatory JSON objects shown in the table below:

JSON Required Data Fields Description Field Data Type
domain* The domain in which the user account to which the authenticator to be assigned resides. Type: string
minLength: 1
maxLength: 255
example: ospanuser-mail
userID* The identifier for the user to which the authenticator will be assigned Type: string
minLength: 1
maxLength: 255
example: iaa_user

Calling the Endpoint

At this point, we are ready to make a RESTful call to Authenticators Assignment endpoint using the IAA interactive Sandbox API. To make the call, click on the “Try it out” button shown in the screenshot below and located to the right of the HTTP 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.

OneSpan-BlogImage-Authenticator-Assignment-Endpoint_2_2

Response Payload

Below is an example of the returned response body of a successful call to assign an authenticator 


{

  "applications": [

    {

      "name": "ACTIVATION",

      "type": "MA"

    }

  ],

  "created": "2018-09-07T11:52:32Z",

  "domain": "osiaa4-mailinator",

  "lastModified": "2020-09-15T04:40:28Z",

  "serialNumber": "VDS0066822",

  "activation": {

    "activationsCount": "2",

    "locationsCount": "0",

    "bound": false,

  "lastActivated": "2020-09-10T04:40:28Z"

  },

  "assignedUserID": "userid1",

  "authenticatorType": "DAL10",

  "assigned": true

}

Response Payload Fields’ Description 

The following table gives more detailed information on each of the properties from the Response payload above.

Response Object Description Data Type
applications* List of applications supported by the authenticator. Each entry will have the name and type of an application  Type: JSON list
Example: "applications": [{
          "name": ACTIVATION",
          "type": "MA"
        } ]

assigned*  


    

Signifies if this authenticator is assigned to a user. Type: boolean
Example: True or False
created* Creation timestamp for the authenticator. Type: string
Example: 2019-02-04T11:42:39Z
domain* The domain in which the user account to which the authenticator to be assigned resides. Type: string
minLength: 1
maxLength: 255
example: ospanuser-mail
lastModified* Last modified timestamp for the authenticator.

Type: string

Example: 2019-02-04T11:42:39Z

serialNumber* The serial number of the authenticator. Type: string
Example: “VDS0066822“
activation It will have four attributes, “bound” to indicate if the authenticator is linked to a specific device, “activationsCount” to show the number of activations. “lastActivated” to show the last activated timestamp for the authenticator. “locationsCount” to show the number of activation locations. Type: JSON list
Example: See the response payload above
assignedUserID The user this authenticator is assigned to. Type: string
Example: “iaa_user1”
authenticatorType The type of the authenticator. Type: string
Example: “DAL10”

In this blog, we explained how to leverage the “Assign Authenticator” endpoint to allocate a Digipass authenticator to an end user through the IAA Sandbox API. 

If you have any questions regarding this blog, feel free to reach us on the OneSpan Community Portal Forums

OneSpan Developer: Intelligent Adaptive Authentication – Authenticator Assignment Endpoint

OneSpan Developer Community

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

Join Today