OpenID API Request Samples for Offline Validation

The following are examples of OpenID Connect REST API requests to authenticate the end user or perform offline transaction signing when the HID Approve device is offline.

The requests illustrate how to implement the bank’s web portal role as described in the use cases Authenticate Using a HID Approve Secure Code and Sign a Transaction.

The following requests use the HID OpenID-specific Custom request parameters.

Before sending requests for the end user, the banking application must authenticate itself to get an access_token (in this example, using the spl-api direct user and OpenID Connect REST API, and where myserver is a placeholder for the ActivID Appliance server host name).

Copy 
POST https://myserver:8445/idp/ONLINEBANK/authn/token
Body
        grant_type=client_credentials&client_id=spl-api&client_secret=password01
 
Response
        header
            {Cache-Control=no-store, Connection=keep-alive, Content-Length=141, Content-Type=application/json;charset=UTF-8, Date=Thu, 30 Nov 2017 10:50:38 GMT, Pragma=no-cache, Server=JBoss-EAP/7, X-Powered-By=Undertow/1}
        content
{"access_token":"RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay","token_type":"Bearer","expires_in":1576800}

The following requests are then sent on behalf of the banking application by passing the access_token value in the Authorization=Bearer header of the request.

Authentication of End User using OATH OTP Validation

In this use case, the end user generates an OTP on the HID Approve device, and then this OTP is entered into the bank’s web portal that performed the authentication for the end user using the following request:

Copy 
POST https://myserver:8445/idp/ONLINEBANK/authn/token
header
    Authorization=Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay, 
    Content-Type=application/x-www-form-urlencoded; charset=UTF-8
Body
    mode=SYNCHRONOUS&password=129066&grant_type=password&authType=AT_CUSTOTP&client_id=spl-api&username=myTestUser1
 
Response
        {"access_token":"BB4OEAAAAWAie8x6RhgknupH00I0AHY0Gcu2FLHn","token_type":"Bearer","expires_in":86400}
Note: In the above request body, mode and authType are HID OpenID custom extensions:

  • mode=SYNCHRONOUS must be used for OTP authentication.

  • authType can be used to specify the authentication policy to use (overriding the value defined in the spl-api adapter definition).

Authentication of End User using OATH OCRA Challenge/Response

In this use case, the bank’s web portal displays a challenge, and the user then enters the challenge into the HID Approve device, resulting in an OTP.

Note: The bank’s web portal generates the challenge on the ActivID Appliance server using the SCIM REST API (for further information about getting challenges, refer to the ActivID Appliance SCIM API Reference Guide).

The bank’s web portal then performs the authentication for the end user using the following request:

Copy 
POST https://myserver:8445/idp/ONLINEBANK/authn/token
header
    Authorization=Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay, 
    Content-Type=application/x-www-form-urlencoded; charset=UTF-8
Body
    mode=ASYNCHRONOUS&password=47808082&device_id=13158&grant_type=password&channel=CH_CSTPORT&authType=AT_CUSTOTP&client_id=spl-api&username=myTestUser1
 
Response
        {"access_token":"BB4OEAAAAWAibm+ATQlKdxEXJa4dLgBHGNV\/4tp2","token_type":"Bearer","expires_in":86400}
Note: In the above request body, mode, authType and channel are HID OpenID custom extensions:

  • mode= ASYNCHRONOUS must be used for Challenge/response authentication.

  • authType can be used to specify the authentication policy to use (overriding the value defined in the spl-api adapter definition).

  • channel can be used to specify the ActivID Appliance channel (overriding the value defined in the spl-api adapter definition).

Offline Transaction Validation using OATH OCRA Signature

In this use case, the bank’s web portal displays the content to be signed (in this example, 3 fields), and the user then enters the content of the into the HID Approve device, resulting in an OTP.

In the sample below, the value of the 3 fields are:

  • AccountId1

  • TransactionId1

  • 10000

The bank’s web portal then performs the signature of the transaction for the end user using the following request:

Copy 
POST https://myserver:8445/idp/ONLINEBANK/authn/token
header 
Authorization=Bearer RTp7HwAAAWAMj+AIg2gHdeU4XEOGGNhpt7PaRlay
Content-Type=application/x-www-form-urlencoded; charset=UTF-8 
Body 
mode=SIGNING&password=21035914&device_id=13158&grant_type=password&context=sign1%3AAccountId1%3Afalse sign2%3ATransactionId1%3Afalse sign3%3A10000%3Afalse&channel=CH_CSTPORT&authType=AT_CUSTOTP&client_id=spl-api&username=myTestUser1
 
Response
        {"access_token":"BB4OEAAAAWAid4GiwDz5bt6yb\/aHz\/0BlMFavrQV","token_type":"Bearer","expires_in":86400}
Note: In the above request body, mode, authType, channel and context are HID OpenID custom extensions:

  • mode= SIGNING must be used for OCRA signature.

  • authType can be used to specify the authentication policy to use (overriding the value defined in the spl-api adapter definition).

  • channel can be used to specify the ActivID Appliance channel (overriding the value defined in the spl-api adapter definition).

  • context defines a specific context for the request (in this example, it is used to pass the transaction fields to sign).

 

context=sign1%3AAccountId1%3Afalse+sign2%3ATransactionId1%3Afalse+sign3%3A10000%3Afalse+

In the context of this call (transaction signing), the syntax is:

Copy 
sign<fieldindex>%3A<value>%3A<auditFlag>

Where:

  • sign is the prefix to be used for the field to sign.

  • <fieldindex> is the index of the field to sign (same order as displayed on the HID Approve device).

  • %3A is the escaped value for the ‘:’ character that is used to separate the fields to sign.

  • <value> field is the value as displayed on bank portal.

  • <auditFlag> is a boolean indicating that the field must be part of the audit record.