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 web service, you must first be a OneSpan Community member and sign up for a free Intelligent Adaptive Authentication sandbox account. Here are step-by-step 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 this detailed user’s registration blog.
Endpoint URL
https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/authenticators/{serial_Number}
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:
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.
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.
Check out more of the Authenticators’ category endpoints:
OneSpan Developer Community
Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.
Join Today
