User Authentication with an OTP Device

Create an OTP Device Authenticator for a User

What you need:

A bearer token (Access token) obtained by authenticating a privileged user (Organization Administrator, Client ID M2M) through an Authentication flow.

You need a privileged user to have enough permissions to perform the actions listed below. Using a bearer token from an non-privileged user / Client ID will result in 401 / 403 HTTP responses from the APIs. For further information, see Enabling User Authentication.
A created User, see Managing Users, Groups and Roles.
A device setup in the HID Authentication Service, see Managing Devices and Credentials

In order to use the OTP device, we need to create and assign an Authenticator to the user, by selecting an OTP-based Authentication policy.

The policy to use is: AT_OTP

Important:

Choosing the right device type when using OTP devices with the Authentication Service is very important. Each device type is defined based on the model of the device and depends on the algorithm used.

For example, when working with the device called "Pocket Token", multiple algorithms are available:

Device type	Algorithm	Authentication method	Credential type
DT_POCK_OT	Oath Time algorithm	Synchronous → OTP authentication	CT_AIOT
DT_POCK_OE	Oath Event algorithm	Synchronous → OTP authentication	CT_AIOE
DT_POCK_OA	Oath OCRA algorithm	Asynchronous → Challenge response authentication	CT_AIOCRA
DT_POCK_OC	Oath OCRA algorithm	Asynchronous → Challenge response authentication	CT_AIOCRA8
DT_POCK_TD	Oath TDS algorithm	Asynchronous → transaction signing authentication	CT_AITDS8

The device types with synchronous method can ONLY be used for authentication using OTP ( the user only has to generate an OTP on the device and enter it on the login form). For this flow refer to the next paragraph on the page 'Authenticate user with OTP '

The device types with asynchronous method can ONLY be used for authentication with challenge response OR for transaction signing ( the user has to enter OTP generated by the Authentication service on the device, then the device will generate an OTP based on the previous data entered and the user will supply in to the login form). For this flow refer to the next paragraphs on the page 'Authenticate user with challenge-response with OTP device ' and 'Transaction signing with OTP device'

Some device types can support both synchronous and asynchronous methods of authentication.

Most of the device types will be able to support more than one algorithm, it means that they will be configured multiple times, with different ids and different device types. The keys 1,2,3 on the devices can be used to switch between the algorithm.

The authentication policy AT_OTP needs to be created once for a user, you can then assign any number of device types to the user.

The first step is to get the internal Id of the user, so we will search for the user whose external ID is jsmith@company.com. To learn more about internal ID vs external ID, see Internal IDs vs External IDs.

POST https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Users/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 
{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"externalId eq \"jsmith@company.com\"",
   "sortBy":"id",
   "sortOrder":"descending",
   "startIndex":0,
   "count":100
}

The response contains the internal ID, here 52276.

{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:ListResponse"   ],
   "totalResults":1,
   "resources":[
      {
         "schemas":[
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:hid:scim:api:idp:2.0:UserDevice",
            "urn:hid:scim:api:idp:2.0:UserAttribute",
            "urn:hid:scim:api:idp:2.0:UserAuthenticator"         ],
         "id":"52276",
         "externalId":"jsmith@company.com" 
         (...)     
 
      }
   ]
}

Second step is to create the authenticator AT_OTP for the user if it doesn't exist yet:

POST https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Authenticator HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Authenticator"   ],
   "policy":{
      "value":"AT_OTP"   },
   "status":{
      "status":"ENABLED",
      "expiryDate":"2020-05-15T18:15:21+00:00",
      "startDate":"2015-05-15T18:15:21+00:00"   },
   "owner":{
      "value":"52276"   }
}

The response:

{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Authenticator"   ],
   "id":"52276.AT_OTP",
   "externalId":"jsmith@company.com",
   "meta":{
      "resourceType":"Authenticator",
      "created":"2015-05-15T18:15:21Z",
      "location":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Authenticator/52276.AT_OTP",
      "version":"1"   },
   "status":{
      "status":"ENABLED",
      "active":true,
      "expiryDate":"2020-05-15T18:15:21Z",
      "startDate":"2015-05-15T18:15:21Z"   },
   "owner":{
      "type":"User",
      "display":"jsmith@company.com",
      "value":"52276",
      "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Users/52276"   },
   "policy":{
      "display":"AT_OTP",
      "value":"AT_OTP",
      "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Policy/Authenticator/AT_OTP"   }
}

Third step is to get the internal ID of the device, so we will search for the device using the device serial number and the device type. Let's consider in our example that we will use the device with the external ID: 0965516059-1 and the device type DT_POCK_OE.

POST https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Device/.search HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 
{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:SearchRequest"   ],
   "filter":"externalId eq 0973494699-1 and type eq DT_POCK_OE",
   "sortBy":"id",
   "sortOrder":"descending",
   "startIndex":0,
   "count":100
}

The response contains the internal ID, here 96740.

{ 
    "schemas":[ 
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"    ],
    "totalResults":1,
    "resources":[ 
       { 
       "schemas":[ 
          "urn:hid:scim:api:idp:2.0:Device"       ],
    "id":"96740",
    "externalId":"0973494699-1",
    "meta":{ 
       "resourceType":"Device",
       "created":"2015-01-17T13:25:27Z",
       "location":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Device/96742",
       "version":"1"    },
    "type":"DT_POCK_OE",
    "status":{ 
       "status":"ACTIVE",
       "active":true,
       "expiryDate":"2025-11-30T00:00:00Z",
       "startDate":"2017-11-30T00:00:00Z"    },
    "children":[ 
       { 
          "value":"96743",
          "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Credential/96743"       }
    ]
    }]
}

The last step is to assign the device to the user:

POST https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Device/96740 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 
{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Device"   ],
   "id":"96740",
   "owner":{
      "display":"jsmith@company.com"   },
   "status":{
      "status":"ACTIVE",
      "active":true,
      "expiryDate":"2025-11-30T11:54:31+0100",
      "startDate":"2017-11-30T11:54:31+0100"   }
}

The response:

{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Device"   ],
   "id":"96740",
   "externalId":"0973494699-1",
   "meta":{
      "resourceType":"Device",
      "created":"2015-01-17T13:25:27Z",
      "location":"https://server.com/scim/hid/v2/Device/96740",
      "version":"1"   },
   "type":"DT_POCK_OE",
   "status":{
      "status":"ACTIVE",
      "active":true,
      "expiryDate":"2025-11-30T00:00:00Z",
      "startDate":"2017-11-30T00:00:00Z"   },
   "owner":{
      "type":"User",
      "display":"jsmith@company.com",
      "value":"52276",
      "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Users/52276"   },
   "children":[
      {
         "value":"96743",
         "$ref":"https://AAAS_PLATFORM/scim/YOUR_TENANT/v2/Credential/96743"      }
   ]
}

You can assign multiple devices to the user, with different or the same device types.

You simply have to repeat the last 2 steps for each device.

See the next section to see how to authenticate the user against the Authentication Service.

Authenticate the User with an OTP

What you need:

A bearer token of a client ID, obtained by authenticating them against the OpenID API (see Client ID authentication with a password or Client ID authentication with JWT (PKI))
A created user (see Managing Users, Groups and Roles)
An OTP device assigned to the user which supports the 'Synchronous' authentication method

The supported devices use the algorithm:
- Oath Time algorithm (device type ending with OT)
- Oath Event algorithm (device type ending with OE)
- ActivID algorithm (device type ending with AT or AI)
In our example, we will use DT_POCK_OT.
The authenticator AT_OTP assigned to the user

The user has to unlock the OTP device (most of the time protected with PIN).

Most of the devices are support multiple algorithms.

For the first use case, we simply want to generate an OTP, you can use the key 1 on the device (on most of them) for accessing this functionality.

Copy

POST https://[base-server-url]/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
mode=SYNCHRONOUS&grant_type=password&username=jsmith@company.com&password=661107&authType=AT_OTP

The returned response is an access token, it allows you to use the APIs and identifies your user's unique session:

Copy

{
   "access_token":"lGBtAgAAAW\/HiyXZD124ASD0+rjBFEKypV8553Q",
   "token_type":"Bearer",
   "expires_in":86400
}

Now, what to do with that ? See Making the most of OpenID Tokens.

Authenticate a User with Challenge-Response with an OTP Device

What you need:

A bearer token of a Client ID, obtained by authenticating them against the OpenID API (see Client ID authentication with a password or Client ID authentication with JWT (PKI))
A created user (see Managing Users, Groups and Roles)
An OTP device assigned to the user which supports the 'Asynchronous' authentication method.

The supported devices use the algorithm:
- Oath OCRA algorithm (device type ending with OA or OC)
- ActivID algorithm (device type ending with AT or AI)
In our example, we will use DT_POCK_OC.
The authenticator AT_OTP assigned to the user.

This is a three-step operation. We need to know the id of the device to use as well as the id of the user. In our example, the device DT_POCK_OC has the id 96742. The id of our user is 96412.

The first step is to send a request to the Authentication service to generate a secret code, this code is called a challenge:

Copy

POST https://[base-server-url]/v2/Authenticator/96412.AT_OTP HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 
{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Action"   ],
   "urn:hid:scim:api:idp:2.0:Action":{
      "action":"DEVICE-CHALLENGE",
      "attributes":[
         {
            "name":"DEVICE.ID",
            "value":"96742"         },
         {
            "name":"CHANNEL",
            "value":"CH_EXTRAPP"         }
      ]
   }
}

The answer contains the challenge, here it is: 407058

Copy

{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Action"   ],
   "attributes":[
      {
         "name":"CHALLENGE",
         "type":"string",
         "value":"407058",
         "readOnly":false
      },
      {
         "name":"CHALLENGE.ID",
         "type":"string",
         "value":"97260",
         "readOnly":false
      },
      {
         "name":"REQUEST.STATUS",
         "type":"string",
         "value":"1",
         "readOnly":false
      },
      {
         "name":"REQUEST.REASON",
         "type":"string",
         "value":"-1",
         "readOnly":false
      },
      {
         "name":"REQUEST.ERROR_MESSAGE",
         "type":"string",
         "readOnly":false
      }
   ]
}

The second step is to ask the user to enter this challenge on the device. The user has to unlock the OTP device (most of the time protected with PIN). Most of the devices are supporting multiple algorithms.

For this second use case, we want to enter the challenge code and the device will generate an OTP based on this. You can use the key 2 on the device (on most of them) for accessing this functionality. Press 'Ok' after entering the challenge to generate the code. When entering the challenge on my device, the following code is displayed: 60929272.

The last step is to send this new code to the HID Authentication Service:

Copy

POST https://[base-server_url]/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
mode=ASYNCHRONOUS&grant_type=password&device_id=96742&username=jsmith@company.com&password=60929272&channel=CH_EXTRAPP&authType=AT_OTP

The returned response is an access token, it allows you to use the APIs and identifies your user's unique session:

Copy

{
   "access_token":"lGBtAgAAAW\/HnaSRqAXCsnXE29cXEy1CE5JRgF0D",
   "token_type":"Bearer",
   "expires_in":86400
}

Now, what to do with that ? See Making the most of OpenID Tokens.

Transaction Signing with an OTP Device

What you need:

A bearer token of a Client ID, obtained by authenticating them against the OpenID API (see Client ID authentication with a password or Client ID authentication with JWT (PKI))
A created user (see Managing Users, Groups and Roles)
An OTP device assigned to the user which supports the 'Asynchronous' authentication method.

The supported devices use the algorithm:
- Oath TDS algorithm (device type ending with TD) algorithm
In our example, we will use DT_POCK_TD.
The authenticator AT_OTP assigned to the user.

A possible use case for this operation is for example the validation of a bank transaction.

The bank website will be displaying three fields such as AccountID, Amount and TransactionId.

The user will have to enter these three values on the OTP device and it will generate a code.

This code will then be used to authenticate the user/transaction.

This is a two-step operation. We need to know the id of the device to use. In our example, the device DT_POCK_TD has the id 96744.

The first step is to display the fields with the three values to the user and to wait for the user to generate the secret code.

Let's consider in our use case that the bank website is displaying the following information:

AccountID: 1122
Amount: 3344
TransactionId: 5566

The user has to unlock the OTP device (most of the time protected with PIN).

Most of the devices are supporting multiple algorithm.

For this third use case, we want to enter the 3 values and the device will generate a code based on this.

You can use the key three on the device (on most of them) for accessing this functionality. Press 'ok' after entering the first value to continue to the second value input.

When entering the three values on my device, the following code is displayed: 099233

The second step is to authenticate the user/transaction:

Copy

POST https://[base-server-url]/authn/token HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/x-www-form-urlencoded
mode=SIGNING&grant_type=password&device_id=96744&username=jsmith@company.com&password=099233&channel=CH_EXTRAPP&authType=AT_OTP&context=sign1%3A1122%3Afalse%20sign2%3A3344%3Afalse%20sign3%3A5566%3Afalse&noToken=1

In this request, the password that needs to be provided is the secure code generated by the device after entering the 3 transaction values.
The "context" parameter has the format:

context=PARAM1:VALUE1:isForAUDIT PARAM2:VALUE2:isForAudit PARAM3:VALUE3:isForAudit (where isForAudit has value true or false : if false the authentication will not appear in the audit)

where PARAM1, PARAM2 and PARAM3 should be respectively: sign1, sign2 and sign3
where VALUE1, VALUE2 and VALUE3 are the value of the transaction fields that you entered on the device. In our example these values are: 1122, 3344 and 5566

Important:

Do not forget to url encode the context parameters
noToken is a common parameter for OpenID token endpoint. This is useful if an application just needs to validate the password without generating a session each time.

The returned response is an access token, it allows you to use the APIs and identifies your user's unique session.

Response with noToken=1 (no session created):

Copy

{"access_token":"IA==","token_type":"Bearer"}

Response with noToken=0 (session created for the user):

Copy

{
    "access_token":"lGBtAgAAAW\/HpnNwqw3oNwNrqNasdJ2vYezNPPDLG",
    "token_type":"Bearer",
    "expires_in":86400
}

Now, what to do with that ? See Making the most of OpenID Tokens.