Managing Devices and Credentials

The Authentication Service supports a range of authentication mechanisms, based on knowledge, possession and/or inherent factors. The possession based authentication factors leverage possession of a device with a symmetric or a private (asymmetric) key to authenticate the user.
Some common device based authentication mechanisms are SMS or email authentication (possession of mobile phone or email account, respectively), HID Approve and OTP Tokens.

In the HID Authentication Service, devices are assigned to a user and have identifying attributes such as a serial number.
Each device type is configured with a set of credentials. These credentials contain all the secrets used for the authentication or synchronization of the device.

It is possible to manage both devices and credentials, however managing low level credentials is not recommended because of the complexity and the possible negative impact it might have on the device and authenticator validity. It is recommended to manage device authentication factors at the level of devices and authenticators only.

Overview of the Available Devices

This section describes the different categories of devices that can be used for device-based authentication.

For a complete list, see Device Types in the HID Authentication Service

Email and SMS Devices

The Authentication Service supports both email and SMS authentication and transaction validation. More information is available at User authentication with out-of-band email and User authentication with out-of-band SMS.

These devices are assigned to the user during the creation of the authenticator. As an example during the creation of an authenticator of type "AT_OOBSMS", the device type "DT_OOBSMS" needs to be part of the request.

The email address or/and the phone number needs to be registered as an attribute for the user in order to authenticate, since it is not part of the device information.

HID Approve Application

This application is available for iOS, Android and Windows 10 platforms and can be downloaded from the appropriate app store.
HID Approve provides a set of features including: authentication via push notification, OTP authentication, transaction signing and challenge/response authentication. More information is available in User authentication with HID Approve.
The HID Approve application also supports customization of the user interface. The default interface on the mobile phone is similar to the one shown below: 

OTP Devices

These devices are usually referred to as a "Token" and are used to display a secure code (OTP) that can be used only once. They are usually protected from unauthorized use with a PIN code, much like a bank card.

The HID Authentication Service supports a wide range of such devices. The detailed list is available in Device Types in the HID Authentication Service.

For a quick overview of the OTP devices produced by HID Global, see HID ActivID One-Time Password (OTP) Tokens

These tokens support a range of algorithms, for example:

• OATH HOTP (Event-based) OTP

• OATH TOTP (Time-based) OTP

• OATH OCRA Challenge/Response

Before assigning a token to a user, it first needs to be available in your tenant of the HID Authentication Service. More information on that can be found later in this section.

Common Device Management

Some management operations on the devices are not dependent on the type, these common operations will be described in this part only and not for each type of device.

What you need to perform these operations:

• 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 HID Authentication Service APIs.

  For further information about getting a token, see Enabling User Authentication.

• The internal ID of the user or of a device on which you want to perform the operation

Structure of the Device Object

The representation of the device object in SCIM in the HID Authentication Service is: 

{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Device"],
    "id":"72196",
    "externalId":"03d4b15f-747d-4d2a-2404-f638207edc08",
    "meta":{
        "resourceType":"Device",
        "created":"2019-10-17T11:20:26Z",
        "location":"https://[base-server-url]/scim/{tenant}/v2/Device/72196",
        "version":"1"
    },
    "friendlyName":"My Samsung Galaxy S10",
    "type":"DT_TDSV4",
    "status":{
        "status":"ACTIVE",
        "active":true,
        "expiryDate":"2024-10-15T00:00:00Z",
        "startDate":"2017-11-30T00:00:00Z"
    },
    "owner":{
        "type":"User",
        "display":"myUser",
        "value":"57250",
        "$ref":"https://[base-server-url]/scim/{tenant}/v2/Users/57250"
    },
    "children":[
        {
            "value":"71247",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Credential/71247"
        },
        {
            "value":"71246",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Credential/71246"
        },
        {
            "value":"71245",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Credential/71245"
        },
        {
            "value":"71244",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Credential/71244"
        },
        {
            "value":"71243",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Credential/71243"
        },
        {
            "value":"71242",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Credential/71242"
        },
        {
            "value":"71241",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Credential/71241"
        }
    ]
}

We have the following properties described in the JSON object:

• id - represents the internal id of the device

• externalID - represents the external id of the device

• meta object - details on the creation date

• friendly name - given name to the device to identify it easily

• type - device type (in our example DT_TDSV4 is an HID Approve device type)

• status - details about the status of the device; whether active or not and the expiry date

• owner - details about the owner of the device

• children - references to all the credentials associated to the device

List Devices

Similar to the other resources on the HID Authentication Service, it is possible to retrieve the list of devices using the search endpoint:

POST https://[base-server-url]/scim/{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" : "owner.value eq 2304",
}

A set of filters are available on the device search endpoint:

The search endpoint will return a list of the device objects that matches the filter in the request.

Get Details about a Single Device

There are multiple ways to get details about a single device - using the "search" endpoint, described earlier, or with the GET method.

To use GET, the internal id of the device needs to be known. In our example we will use the device id 72196

The request will then be: 

GET https://[base-server-url]/scim/{tenant}/v2/Device/72196 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"

The response will be a single device object.

If we do not know the device id, then we can combine filters in the search device request to narrow down the result to a specific device using the 'and' operator.

For example, if we want details about the push device(s) for a given user, we could use the filter: 

POST https://[base-server-url]/scim/{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" : "owner.value eq 2304 and type eq DT_TDSV4",
}

The response will be a single device object.

Assign, Unassign and Update a Device

The update endpoint for devices is used to assign a device to a user, to unassign it and to modify the status of the device.

The action to be conducted on the device is based on the field that are or not specified in the request.

• If owner.value or owner.display is empty, the device will be unassigned from a user.

• If owner.value or owner.display is not empty, the device will be assigned to the indicated user.

• If the owner section is not indicated, the ownership is not modified.

• If one of the status parameter is not empty, it will overwrite the existing value.

• If the status section is not indicated, the status is not modified.

The detailed list of updatable attributes:

• status.status

• status.startDate

• status.expiryDate

• owner.display (user.externalId)

• owner.value (user.id)

There are some restriction about the status change, please find bellow the possible transitions: 

This means that once the device is updated with the status "Revoked" it can only be terminated. It will be impossible to use it after that.

Sample request for assigning a device and changing its status to active: 

PUT https://[base-server-url]/scim/{tenant}/v2/Device/72196 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Device"],
    "status":{
        "status":"ACTIVE"}
    "owner" : {
        "value" : "2304"}
}

In the response you will be able to see that the changes were taken into account. The device will be assigned to our user and ready for use.

Sample request for unassigning a device and changing its status to suspended: 

PUT https://[base-server-url]/scim/{tenant}/v2/Device/72196 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Device"],
    "status":{
        "status":"SUSPENDED"}
    "owner" : {
        "value" : ""}
}

Delete a Device

Like the other resources on the Authentication Service, the "delete" endpoint is used to delete a device.

The sample request for deleting a device is: 

DELETE https://[base-server-url]/scim/{tenant}/v2/Device/72196 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN

A 204 response with no content indicates that the device was properly deleted.

Registering SMS or Email OTP Devices

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 Authentication Service APIs. To know how to get a token, see Enabling User Authentication.

• The internal ID of the user you want to perform the operation on.

As previously described, the creation of the device type is automatically done during the creation of the authenticator.

In order to set up the out-of-band with SMS or with email , we need to create and assign an Authenticator to the user, by selecting a Device-based Authentication policy. 

The available policies are: 

• AT_OOBSMS - Out-of-band SMS policy designed to be used with SCIM API's only. This policy requires an activation code.

• AT_TXOOB - Out of band SMS policy designed to be used for transaction signing. 

• AT_OOBEML - Out-of-band email policy designed to be used with SCIM API's only. This policy requires an activation code.

To know more about the details of those policies, see Authentication Policies in the HID Authentication Service. 

The creation of the authenticator is done using the Authenticator endpoint with a POST request. 

• Fill up the policy attribute with the desired out-of-band email or sms policy. 

• The owner attribute is pointing to the internal ID of the user. 

• The activationCode attribute is mandatory when using AT_OOBEML and AT_OOBSMS policies.  It can be an alphanumeric or numeric string.

• The  Action  attribute is an object containing the key word for registering the out-of-band authenticator and the name of the device type associated with the out-of-band policy, refer to the following table to determine which device type to use : 

• When registering the authenticator type  'AT_TXOOB', the credential type needs to be explicitly added to the 'Action' element: 

"urn:hid:scim:api:idp:2.0:Action": {
      "action": "REGISTER-OOB",
      "attributes": [
          {
             "name": "OOB_CREDENTIALTYPE_CODE",
             "value": "CT_TXOOB"
          },
          {
             "name": "OOB_DEVICETYPE_CODE",
             "value": "DT_TXOOB"
          }
 
   ]}

The request for the creation of the authenticator is similar to: 

POST https://[base-server-url]/scim/{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_OOBEML"
   },
   "owner":{
      "value":"52276"
   },
   "urn:hid:scim:api:idp:2.0:Action": {
      "action": "REGISTER-OOB",
      "attributes": [
          {
             "name": "OOB_DEVICETYPE_CODE",
             "value": "DT_OOBEML"
          }
   ]},
   "policy": {
   "value": "AT_OOBEML"
   },
      "activationCode":"activationSecretCode",
}

The user's authenticator is then ready, the device and the credentials are created during this operation. 

The response contains new attributes: 

• The id attribute, that the Authentication Service generated by concatenating the user internal ID and the Authentication policy code. Here  52276.AT_OOBEML.

• The statistics object.

• The activation code.

To know more about the detail of Authenticators, see Managing a User or Client ID's Authenticators. 

{
   "schemas":[
      "urn:hid:scim:api:idp:2.0:Authenticator",
   ],
   "id":"52276.AT_OOBEML",
   "externalId":"jsmith@company.com",
   "meta":{
      "resourceType":"Authenticator",
      "created":"2015-05-15T18:15:21Z",
      "location":"https://[base-server-url]/scim/{tenant}/v2/Authenticator/52276.AT_OOBEML",
      "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://[base-server-url]/scim/{tenant}/v2/Users/52276"
   },
   "statistics":{
      "consecutiveFailed":"0",
      "consecutiveSuccess":"0",
      "maximumNumberOfUsages":"0",
      "totalFailed":"0",
      "totalSuccess":"0"
   },
   "policy":{
      "display":"AT_OOBEML",
      "value":"AT_OOBEML",
      "$ref":"https://[base-server-url]/configuration/{tenant}/v2/Policy/Authenticator/AT_OOBEML"
   },
   "activationCode":"activationSecretCode"
}

HID Approve Device Management

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 the 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 Authentication Service APIs. To know how to get a token, see Enabling User Authentication.

• The internal ID of the user to who you want to assign the device.

To enable the authentication with a HID Approve device, a two-step process needs to be followed : 

• Creating the device and assigning it to the user. This device will be of the type "push device".

• Creating a device provisioning request (an invitation to be onboarded for the HID Approve app)

Create a Device for a User

There is a set of device types that can be used with the HID approve app. It is important to choose the correct one that will fit the authentication mechanism implemented. :

• DT_TDSV4 is used for authenticating with OpenID API (token endpoint with CIBA) as well as second authentication factor with our IDP portal, using AT_EMPPWD as primary password authentication.

• DT_TDSV4F is similar to DT_TDSV4 but its implementation complies with FIPS 140-2 cryptographic algorithms

It is also possible to create copies of these devices type and customize some of the parameters. For more details on that please refer to device customization.

To know more about available device types, see Device Types in the HID Authentication Service.

Sample request for creating the device type DT_TDSV4: 

POST https://[base-server-url]/scim/{tenant}/v2/Device HTTP/1.1
Authorization: Bearer YOUR_CLIENTID_BEARER_TOKEN
Content-Type: application/scim+json    
        
{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Device"
    ],
    "externalId": "test@mail.com-331",
    "type": "DT_TDSV4",
    "status": {
        "status": "PENDING",
        "active": false,
        "expiryDate": "2020-11-30T11:54:31+0100",
        "startDate": "2017-11-30T11:54:31+0100"
    }
}

The externalID in the request should be a unique identifier for the device; it should be unique across all the devices in the tenant.

The device has to be created with the status "PENDING" and the parameter "active" set to "false".

The response contains the internal ID of the device:

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Device"
    ],
    "id": "11845",
    "externalId": "test@mail.com-331",
    (...)
}

The device needs to be assigned to the user, this can be done using the process described previously on the page (the internal id that we received when creating the device is added at the end of the endpoint url):

PUT https://[base-server-url]/scim/{tenant}/v2/Device/11845 HTTP/1.1
Authorization: Bearer YOUR_CLIENTID_BEARER_TOKEN
Content-Type: application/scim+json
{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Device"
    ],
    "owner": {
        "display": "test@mail.com"
    },
}

The "owner.display" parameter is the external id of the user, the parameter "owner.value" could have been used as well; with the internal id of the user .

The device is now created and assigned to the user. The second step is to create the credentials for the device. This will be completed by generating an invitation that the user will enter in the HID Approve app. The app will then communicate directly with the Authentication Service and after a secure exchange of secrets, the credentials will be created on both sides. This invitation is also referred to as a device provisioning request.

Provisioning Request Management

Create a Device Provisioning Request

The output of this process will be an invitation that the user will be able to use to register the HID Approve app.

A sample request for creating the invitation for the device that was created earlier: 

POST https://[base-server-url]/scim/{tenant}/v2/Device/Provision HTTP/1.1
Authorization: Bearer YOUR_CLIENTID_BEARER_TOKEN
Content-Type: application/scim+json    
        
{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Provision"
    ],
    "deviceType": "DT_TDSV4",
    "description": "did=11845,url=AAAS_PLATFORM/YOUR_TENANT,cb_url=https://your-application/callback,cb_notif_token=8d67dc78-7faa-4d41-aabd-67707b374255,pch=CH_TDSPROV,pth=AT_TDSOOB,pct=CT_TDSOOB,pdt=DT_TDSOOB,mod=GEN,sec=",
    "owner": {
        "value": "11072"
    },
    "attributes": [
        {
            "name": "AUTH_TYPE",
            "value": "AT_SMK",
            "readOnly": false
        }
    ]    
}    

Some of the parameters in the request are fixed values, for example: 

• The attributes: this object is defining the authentication policy that will be used for updating the credentials on the HID approve app

• In the description object: the following string is constant and is defining the mobile registration credentials and channel to use :"pch=CH_TDSPROV,pth=AT_TDSOOB,pct=CT_TDSOOB,pdt=DT_TDSOOB,mod=GEN,sec="

The important parameters to specify are: 

• deviceType: the type of the push device

• owner.value: internal id of the user owning the device

• in the description object: 

  • did: internal id of the device

  • url: The format of the value is : AAAS_PLATFORM/YOUR_TENANT
    It is very important to not specify "https://" in front of this value

  • cb_url: callback server on which a notification will be sent upon registration of HID approve app

  • cb_notif_token: this value will be returned with the notification on the callback url. Its purpose is to validate that the notification received corresponds to this device provisioning request. It is recommended to use a random value for that.

In the response, the information required for generating the invitation for the user is returned: 

{
    "schemas": [
        "urn:hid:scim:api:idp:2.0:Provision"
    ],
    "id": "11052",
    "meta": {
        "resourceType": "Provision",
        "created": "2020-01-22T17:21:17Z",
        "location": "https://[base-server-url]/scim/{tenant}/v2/Device/Provision/11052",
        "version": "1"
    },
    "deviceType": "DT_TDSV4",
    "status": {
        "status": "UNPROCESSED",
        "active": false
    },
    "owner": {
        "type": "User",
        "display": "test@mail.com",
        "value": "11072",
        "$ref": "https://[base-server-url]/scim/{tenant}/v2/Users/11072"
    },
    "attributes": [
    {
        "name": "PROV_MSG",
        "type": "string",
        "value": "{\"ver\":\"v8\",\"url\":\"[base-server-url]/scim/{tenant}",\"uid\":\"test@mail.com\",\"did\":\"11845\",\"dty\":\"DT_TDSV4\",\"dir\":\"11052\",\"pch\":\"CH_TDSPROV\",\"pth\":\"AT_TDSOOB\",\"sec\":\"\",\"pss\":\"RDNJSTVJSUJXWA==\"}",
        "readOnly": false
    }
    ]
}

There are two ways to display the invitation to the user, by generating a QR code based on the field "value" in the "attributes" object: {\"ver\":\"v8\",\"url\":\"[base-server-url]/scim/{tenant}",\"uid\":\"test@mail.com\",\"did\":\"11845\",\"dty\":\"DT_TDSV4\",\"dir\":\"11052\",\"pch\":\"CH_TDSPROV\",\"pth\":\"AT_TDSOOB\",\"sec\":\"\",\"pss\":\"RDNJSTVJSUJXWA==\"}

The properties recommended for the QR code are : version="6" and error-correction-level="L"
It is possible to use different properties for the QR code if needed.

The second way to display the invitation, is to extract the three pieces of information from the "value" in the "attributes" object. The user will have to enter them manually on the phone (this process is referred as manual registration): 

• service url - value can be extracted directly from the "url" property

• user id - value can be extracted directly from the "uid" property

• invitation code - this code is store in the "pss" property. It is encoded in base 64

  After decoding the value, it will represent the invitation code for the user.

Once the user registers with the HID Approve app. A notification is sent to the callback url specified during the creation of the device provisioning.

When the device registration is successful, a set of authenticators and credentials are created for the user. These authenticators support the authentication mechanisms in HID Approve and the secrets are stored in the credentials :

• AT_SMK - authentication policy is used internally by the service to synchronize HID Approve

• AT_PASA - authentication policy used for the push authentication flow

  This policy is used for login validation.

• AT_TDS - authentication policy used for push authentication flow

  This policy is used for action validation.

• AT_EMPOTP - authentication policy used for the OTP authentication flow, as well as the Challenge/Response authentication flow

List Device Provisioning Requests

Similar to the other resources on the Authentication Service, it is possible to retrieve the list of device provisioning requests using the search endpoint:

POST https://[base-server-url]/scim/{tenant}/v2/Device/Provision/.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" : "owner.value eq 2304 and deviceType eq DT_TDSV4 and status.status eq UNPROCESSED",
}

A set of filter is available on the device search endpoint:

The search endpoint will return a list of the device provisioning objects that matches the filter in the request.

Sample response:

{
    "schemas":[
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults":1,
    "resources":[
    {
        "schemas":[
            "urn:hid:scim:api:idp:2.0:Provision"
        ],
        "id":"23920",
        "meta":{
            "resourceType":"Provision",
            "created":"2020-02-25T00:00:00Z",
            "location":"https://[base-server-url]/scim/{tenant}/v2/Device/Provision/23920",
            "version":"1"
        },
        "deviceType":"DT_TDSV4",
        "status":{
            "status":"UNPROCESSED",
            "active":false
        },
        "owner":{
            "type":"User",
            "display":"test@mail.com",
            "value":"11072",
            "$ref":"https://[base-server-url]/scim/{tenant}/v2/Users/11072"
        },
        "attributes":[]
    }]
}

Get Details about a Single Device Provisioning Request

To use the get endpoint, the internal id of the device provisioning needs to be known. In our example, we will use the device provisioning with id: 23920

The request will then be: 

GET https://[base-server-url]/scim/{tenant}/v2/Device/Provision/23920 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"

The response will be a single device provisioning request object.

Delete a Device Provisioning Request

Like the other resources on the Authentication Service, the delete endpoint is used to delete a device provisioning request.

The sample request for deleting a device provisioning request is: 

DELETE https://[base-server-url]/scim/{tenant}/v2/Device/Provision/23920 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN

A 204 response with no content indicates that the device was properly deleted.

Token Management

HID Tokens exist in different sizes and shapes. They are designed for different use cases and different authentication mechanisms. Depending on the algorithms configured on the Token, the user will be able to authenticate using the OTP mechanism or the challenge/response flow. For more information about the available authentication, see User authentication with Device OTP.

The current list of HID tokens supported by the Authentication Service is:

The algorithm marked with "option" can be added to the Token when specified when ordering the Token to the manufacturer.

Each algorithm corresponds to one credential type in the Authentication Service (except for the OCRA algorithm because of the different versions of it): 

Importing Tokens

File Format

To import Tokens into the Authentication Service, a file describing the properties of the Tokens is needed. This file is delivered with the shipped Tokens.

Two formats exist for this file : PSKC (open standard, RFC6030) and SDS (HID proprietary).

The PSKC format is key (credential) oriented, each entry in a PSKC file concerns only one credential for one device with one algorithm and the corresponding key and parameters. One new device with a credential for each entry will be created during the import.

If the device contains several credentials (multi-slot devices), several entries with the same device serial number are present in the PSKC file. To support these multi-slots use cases, the Authentication Service creates one device/credential per entry but to avoid conflicts with several devices with the same serial number it appends an incremental digit to the end of the serial number.

Today, only the OATH and OCRA algorithms are supported in PSKC files, other algorithms (ActivID Time/Event based for example), if any, are ignored.

View PSKC file example

<?xml version="1.0" encoding="UTF-8"?><KeyContainer Version="1.0" xmlns="urn:ietf:params:xml:ns:keyprov:pskc" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"><EncryptionKey><ds:KeyName>Pre-shared-key</ds:KeyName></EncryptionKey><MACMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1"><MACKey><xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/><xenc:CipherData><xenc:CipherValue>wHj+S5RVh4rJK12XzeeqOA5LMEB5r9qEJUPn0e7EIdq</xenc:CipherValue></xenc:CipherData></MACKey></MACMethod><KeyPackage><DeviceInfo><Manufacturer>oath.AI</Manufacturer><SerialNo>0965516020</SerialNo></DeviceInfo><Key Id="0965516020" Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:totp"><AlgorithmParameters><ResponseFormat Length="6" Encoding="DECIMAL"/></AlgorithmParameters><Data><Secret><EncryptedValue><xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/><xenc:CipherData><xenc:CipherValue>h0mzdMS1e2rrRsb1HH51RiirCHyM/bnedjzg</xenc:CipherValue></xenc:CipherData></EncryptedValue><ValueMAC>QRnab2fmg+pkzQ=</ValueMAC></Secret><Time><PlainValue>0</PlainValue></Time><TimeInterval><PlainValue>30</PlainValue></TimeInterval></Data></Key></KeyPackage><KeyPackage><DeviceInfo><Manufacturer>oath.AI</Manufacturer><SerialNo>0965516020</SerialNo></DeviceInfo><Key Id="0965516020" Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:ocra"><AlgorithmParameters><Suite>OCRA-1:HOTP-SHA1-8:QN08</Suite><ChallengeFormat Min="8" Max="8" Encoding="DECIMAL"/><ResponseFormat Length="8" Encoding="DECIMAL"/></AlgorithmParameters><Data><Secret><EncryptedValue><xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/><xenc:CipherData><xenc:CipherValue>PyUUQRiRceuqNFOV5RqGOQ/xMKFaczR0MHpO</xenc:CipherValue></xenc:CipherData></EncryptedValue><ValueMAC>6rfK8hU+T7EwM=</ValueMAC></Secret></Data></Key></KeyPackage><KeyPackage><DeviceInfo><Manufacturer>oath.AI</Manufacturer><SerialNo>0965516026</SerialNo></DeviceInfo><Key Id="0965516026" Algorithm="urn:ietf:params:xml:ns:keyprov:pskc:hotp"><AlgorithmParameters><ResponseFormat Length="6" Encoding="DECIMAL"/></AlgorithmParameters><Data><Secret><EncryptedValue><xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/><xenc:CipherData><xenc:CipherValue>F7WNdhZl7KerUSH0wi1r4xL1NWTIWnc6rTg9baJE/9O/Z1b</xenc:CipherValue></xenc:CipherData></EncryptedValue><ValueMAC>mRF2y40rFngGUK0nY=</ValueMAC></Secret><Time><PlainValue>0</PlainValue></Time><TimeInterval><PlainValue>30</PlainValue></TimeInterval></Data></Key></KeyPackage>

There are a total of two physical devices in this sample file.
The algorithms "hotp" (short name for urn:ietf:params:xml:ns:keyprov:pskc:totp) , "totp" (for "urn:ietf:params:xml:ns:keyprov:pskc:totp") or "ocra" ( for "urn:ietf:params:xml:ns:keyprov:pskc:ocra") are also visible in this file.

The first device with the id:

• 0965516020 is supporting two algorithms : "totp" and "ocra"

• 0965516026 is only supporting the "hotp" algorithm

A total of three devices will then be created in the Authentication Service during the import - one device for each algorithm.

The second file format, SDS format, is device oriented, each entry in the SDS file is one device containing all the credentials that belong to it. Today all the devices contained in the same SDS file must be of the same type (all Flexi Token or all Pocket Token for example).

SDS files are generally encrypted, and a password needs to be delivered with the file.

Depending on the amount of devices to import, the operation can be conducted in a synchronous or asynchronous manner.

Choosing the right device type when importing devices to the Authentication Service is very important. Each device type is defined based on the model of the device and depends on the algorithm used inside.  

For example, when working with a "Pocket Token" device, multiple algorithms are available and specified in the file delivered with the tokens, all the possible algorithms are: 

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 log in form). For details on this flow, see 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 in the device, then the device will generate an secure code based on the previous data entered and the user will provide it to the application). For more details, see Authenticate user with challenge-response with OTP device and Transaction signing with OTP device.

The device types with both methods can support all the available authentication mechanisms.

Synchronous Import

What you need:

• A bearer token (Access token) obtained by authenticating of a user with the role RL_DEVADMIN. To know how to get a token, see Enabling User Authentication.

• The PSKC or SDS file describing the devices to import.

The synchronous import can be used when the file describing the Tokens is less than 1,5 MB.

As an example, the PSKC file presented in the example earlier will be imported to the Authentication Service.

It is mandatory to know the type of Tokens that are defined in the file. We will consider that the Tokens are Flexi Token; so the device types will be starting with "DT_FXT_". To have the complete list of device type available.

The other information that needs to be extracted from the PSKC file is the algorithms that are defined. A device type will have to be associated for each algorithm.

In our example we have: 

• TOTP will be associated with DT_FXT_OT

• HOTP will be associated with DT_FXT_OE

• OCRA will be associated with DT_FXT_OA

Refer to the list of device types in order to find the association between the device type and the algorithm.

Reminder: Only devices with hotp, totp or ocra algorithm with be imported, any other entry using a different algo will be just skipped in a PSKC file.

POST https://[base-server-url]/scim/{tenant}/v2/Device/.import HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: application/scim+json
{
    "adapter": "OATH-PSKC",
    "mapping": [
    {
        "deviceType": "DT_FXT_OE",
        "algo": "HOTP"
    },
    {
        "deviceType": "DT_FXT_OT",
        "algo": "TOTP"
    },
    {
        "deviceType": "DT_FXT_OA",
        "algo": "OCRA"
    }
    ],
    "encryptionKey": 123456789010111213,
    "resyncWindow": 20,
    "status": "ACTIVE",
    "payload": "<Base64 encoded file>",
    "async": false
}

• The adapter parameter can have the values "OATH-PSKC" or "SDS" depending on the file format used.

• The mapping object is representing the association of an algorithm with a device type. The algorithms are not case sensitive.
  If an algorithm is defined in the file it must have a device type associated with it.

• The encryption key is delivered with the file.

• The payload is the file encoded in base 64.

• The parameter "async" set to "false" is needed for synchronous device import.

Some optional parameters can be included in the request: 

• correlationId - If no correlationId is specified, a random one is generated. The correlationId will appear in all audit records for this import.

• startDate - Can be used to define a "valid from" date for devices and credentials (format dd/MM/yyyy).

• endDate - Can be used to define a "valid to" date for devices and credentials (format dd/MM/yyyy).

The response from a synchronous import is:

{
    "results": [{
        "device": {
            "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
            "id": "370908",
            "externalId": "0965516020-1",
            "meta": {
                "resourceType": "Device",
                "location": "[base-server-url]/scim/{tenant}/v2/Device/370908",
                "version": "1"
            },
            "type": "DT_FXT_OT",
            "status": {
                "status": "ACTIVE",
                "active": true
                }
            },
            "result": 101,
            "reason": "Imported Token"
        }, 
        {
            "device": {
            "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
            "id": "370910",
            "externalId": "0965516020-2",
            "meta": {
                "resourceType": "Device",
                "location": "[base-server-url]/scim/{tenant}/v2/Device/370910",
                "version": "1"
            },
            "type": "DT_FXT_OA",
            "status": {
                "status": "ACTIVE",
                "active": true
            }
            },
            "result": 101,
            "reason": "Imported Token"
        }, 
        {
            "device": {
            "schemas": ["urn:hid:scim:api:idp:2.0:Device"],
            "id": "370912",
            "externalId": "0965516026",
            "meta": {
                "resourceType": "Device",
                "location": "[base-server-url]/scim/{tenant}/v2/Device/370912",
                "version": "1"
            },
            "type": "DT_FXT_OE",
            "status": {
                "status": "ACTIVE",
                "active": true
            }
            },
            "result": 101,
            "reason": "Imported Token"
    }
    ]
}

The response contains a list of devices that were imported - or the error if one occurred.

It also returns a result parameter that can have the following values:

Asynchronous Import

The only difference between the asynchronous and the synchronous request for importing devices is the value of the parameter "async"; which should be set to "true" for importing a large amount of devices.

The response sent by the Authentication Service will be different: 

{
	"results": [],
	"correlationId": "1SFCBFBFVCGTCV7QVTBV"
}

The only information in the response is a correlationId. It will be used to retrieve the status of the import through the audit records.

POST https://[base-server-url]/{tenant}/v2/AuditRecords/.search HTTP/1.1
{
"schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
"filter": "correlationId eq 1SFCBFBFVCGTCV7QVTBV and type eq asyncDeviceImport",
"count": 10
}

The correlationID needs to be specified, an additional filter "type" can also be added to retrieve only the information about the: 

• Complete import process, the value for "type" should be "asyncDeviceImport"

• Record for each device added to the HID Authentication Service, the filter value should be "addDevice"

It is also possible to use the filter "serialNumber" to retrieve information about a given device.

The response is a list of all the audit records matching the filters.
If only the correlationID is specified, then the response will contain: 

• One event for the start of the import process

• One event for the end of the import process

• One event for each device imported

Each event is represented by a JWT token in the response.

If a device is not imported, the process will proceed with the next one. The cause of the failure will be available in the event. For more information about events, see Tracking what happens on my Tenant: Audit Logs and Events

Actions on Tokens

For details about the authentication mechanism, see User authentication with Device OTP.

The actions that will be described here are only related to the resynchronization of the device and unlocking the device after entering the wrong PIN too many times.

Resynchronize a Token

It may happen that the Token and the HID Authentication Service are not synchronized anymore. This will be visible when if entering properly the correct OTP, the authentication keep failing.

To force the automatic resynchronization of the device, the following endpoint should be used with the internal id of the device (10588 in our example): 

POST https://[base-server-url]/scim/{tenant}/v2/Device/10588
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "AUTO-SYNCH",
        "attributes": [{
            "name": "OTP",
            "value": "20571257"
        }]        
    }
}

The user needs to generate an OTP on the Token and provide the value in the request.

After this operation, the user will be able to use the Token to authenticate.

Unlock the Token PIN

After entering too many times the wrong PIN on a Token, for security measure it will be locked.

To unlock the token of a user, the following endpoint is available: 

POST https://[base-server-url]/scim/{tenant}/v2/Device/10588
{
    "schemas": ["urn:hid:scim:api:idp:2.0:Action"],
    "urn:hid:scim:api:idp:2.0:Action": {
        "action": "PIN-UNLOCK",
        "attributes": [{
            "name": "CHALLENGE",
            "value": "20571256"
        }]        
    }
}

The user has to generate challenge for PIN unlock on the device and send it to the Authentication Service. The response will contain a secret code that the user will enter in the device.

If the user is entering the wrong secret code five times, the device will be blocked and impossible to use again.

Credential Management

It is not possible to create credentials directly and the only parameter than can be updated is the status of the credential.

Search Credentials

Similar to the other resources, the endpoint to use for search is: 

POST https://[base-server-url]/scim/{tenant}/v2/Credential/.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" : "owner.value eq 2304",
}

The supported list of filters for the credentials: 

The response contains the list of credentials matching the filter: 

{
    "schemas":[
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults":1,
        "resources":[
        {
            "schemas":[
                "urn:hid:scim:api:idp:2.0:Credential"
            ],
            "id":"96535",
            "externalId":"mytestuser@gmail.comCT_ACODESMST",
            "meta":{
                "resourceType":"Credential",
                "created":"2020-01-17T08:59:31Z",
                "location":"https://[base-server-url]/scim/{tenant}/v2/Credential/96535",
                "version":"1"
            },
            "type":"CT_ACODESMST",
            "status":{
                "status":"ACTIVE",
                "active":true,
                "expiryDate":"2021-01-16T08:59:31Z",
                "startDate":"2020-01-17T08:59:31Z"
            },
            "attributes":[
            {
                "name":"EXPIRY_THRESHOLD_OF_ACTIVATION_CODE",
                "type":"string",
                "value":"-1",
                "readOnly":false
            }
            ],
            "totalUsed":"0"
        }
    ]
}

Get Details of a Single Credential

Similar to the other resources, the get endpoint can be used if we know the internal id of the credential: 

GET https://[base-server-url]/scim/{tenant}/v2/Credential/96535 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json" 

The response will contain all the information about the credential.

Update the Status of a Credential

Similar to the update of the status of the other resources, this is done by updating the status object of the device.

The transition between the status is the same as for the devices: 

The detailed list of updatable attributes:

• status.status

• status.startDate

• status.expiryDate

Sample request : 

PUT https://[base-server-url]/scim/{tenant}/v2/Credential/96535 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN
Content-Type: "application/scim+json"
{
    "schemas":[
        "urn:hid:scim:api:idp:2.0:Credential"],
    "status":{
        "status":"SUSPENDED"}
}

Delete a Credential

The delete operation is performed using the following endpoint:

DELETE https://[base-server-url]/scim/{tenant}/v2/Credential/96535 HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN

A 204 response with no content indicates that the credential was correctly deleted.