Bcauthorize Endpoint

Clients can create a request for Client Initiated Backchannel Authentication (CIBA) feedback on operations such as a push-based logon on a mobile device.

https://[base-server-url]/{tenant}/authn/bcauthorize [POST]

Based on the OpenID Connect CIBA Core specifications - section 5, you can use one of the following CIBA modes:

• Push (default) - HID Authentication Service posts the full authentication result to the client
• Poll - the client retrieves the authentication result by polling the HID Authentication Service token endpoint using the authentication request ID as the new grant type

During client registration, the CIBA feedback mode can be configured by setting the backchannel_token_delivery_mode parameter to poll or push.

The client sends a CIBA request using the bcauthorize endpoint when the user initiates an operation on their device.

Using the authentication request ID, HID Authentication Service sends the feedback via the CIBA callback URL defined for your OpenID client.

You can also use the token endpoint to delete (ciba_delete) a pending push request.

For detailed responses, see Retrieve the Authentication Result and Access Token.

Bcauthorize Request

POST https://[base-server-url]/{tenant}/authn/bcauthorize HTTP/1.1
Connection: close
Authorization: Bearer RTp7HwAAAXk3s41v8uBOEA92yE98qTLB1+SKlONh
Content-Type: application/x-www-form-urlencoded
 
{
     "scope": "openid hid-tx-sign",
     "acr_values": "mod-mf",
     "login_hint_token": "eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfVERTIiwidGRzIjoie2Ftb3VudCwgNDAwLjAwfSx7c29ydGNvZGUsMjAtMzAtOTB9LCB7YWNjb3VudF90bywxMjM0LTU2Nzh9IiwiY2hhbm5lbCI6IkNIX1REUyIsInVzZXJjb2RlIjoiYmFua3VzZXIwMSIsImRldmljZWlkIjoiMTEwNTgiLCJjcmVhdGVTZXNzaW9uIjoiMSJ9."
 }

Where:

• scope – is the scope that defines the list of claims (user information) that will be part of the id_token

  The hid-tx-sign scope adds support for custom claims, such as "JWS", "PUK", "approvalstatus" , "deviceid" , "domain".

• login_hint_token – is a JWT token (PlainJWT with no signature or encryption) with the information required to initiate a push-based logon or operation validation approval

Copy

The JWT JSON payload of login_hint_token is:

{
    "authpol":"AT_PASA",
    "tds":"Please validate Logon",
    "channel":"CH_DIRECT",
    "usercode":"MyTestUser",
    "deviceid":"11924",
    "createSession":"0",
    "RMSInfo":"eyJhbGciOiJub25lIn0.eyJUTV9TRVNTSU9OX1NJRCI6InJZRmNtNjVwa2hvYXdHUkZnTjFVUk5YWUhsM1FBcGxIIiwiVE1fQ0xJRU5UX0lQIjoiMTAuMTYuNzEuNzkiLCJUTV9TRVNTSU9OX1RSQU5TRkVSIjoiUFc4RDBUUDVrMmFHZEl2TUlYcU5LM2ZCZ1NnNWVCVjdYSEFIOHNneCIsIlRNX0RFVklDRV9UQUciOiIwT2VuTnFBZGxRM2Fwb1ZmSGhkcmJuZ2F2WDRVajNQVCJ9.",
    "tds_context" : "TXkgdHJhbnNhY3Rpb24gc2FtcGxlIGNvbnRleHQ="
}

Where:

Parameter	Description
usercode	The HID Authentication Service identifier of the targeted user This is not required for userID-less QR code operations.
deviceid	The HID Authentication Service identifier of the targeted device If not set, the notification is sent to the last used device (the active device that has the most recently used credential for the authentication policy in the request). This is not required for userID-less QR code operations.
authpol	The authentication policy to use
channel	The channel to create the logon or operation request on the HID Authentication Service (optional, the default is the channel configured for the OpenID client)
tds	(Optional) The logon or operation validation message to be displayed on the device for approval
createSession	(Optional) Defines if HID Authentication Service will create a sessionid (aka ALSI) if the operation is validated on the device If set to "1", then a sessionid will be created The default value is "0" (no session is created)
tds_context	(Optional) Contains the customer-specific data about the context to be returned with the push authentication result: For a banking application (mobile or web-based), the data is added during transaction creation process (transaction context data) For a mobile application, the data is added during the transaction signature process (transaction signature context data, such as RMS session information or a deep-link to the merchant mobile application that initiated the transaction) The data should be provided as a string or binary of external attributes encoded as Base64 and has a maximum size limit of 1000 characters. The context data (tds_context and mobile_tds_context parameters) is returned as part of the id_token in the retrieved result. For integrations with the HID Approve SDK, the data should be passed in the setStatus method parameters for transaction signing. The login_hint_token is also included in the audit event corresponding to the transaction signature.
mode	Required to indicate that the request is for a userID-less QR code operation and you should set the value to userid_less. This is not required for userID-based requests.
device_type	Required for a userID-less QR code operation to identify the keyID and you should specify the push-based device type. This is not required for userID-based requests.
cal	(Optional) Specifies the default approval status sent to the device for a userID-less QR code operation. This should be a subset (string) of the values defined for the push-based credential type (where the default value is accept|deny|report). If you set the parameter to accept, the request will be automatically signed and the user will not be prompted to approve or decline.
RMSInfo	(Optional) A PlainJWT object with information in the context of Risk Management System integration (for further information, see Risk Management Solution for the HID Authentication Service). The following is an example of the content: Copy {   "TM_CLIENT_IP": "10.16.71.79",   "TM_SESSION_SID": "rYFcm65pkhoawGRFgN1URNXYHl3QAplH",   "TM_DEVICE_TAG": "0OenNqAdlQ3apoVfHhdrbngavX4Uj3PT",   "TM_SESSION_TRANSFER": "PW8D0TP5k2aGdIvMIXqNK3fBgSg5eBV7XHAH8sgx"                         }

Copy

Example of login_hint_token for a userID-less QR code operation:

eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJ0ZHMiOiJ0cmFuc2FjdGlvbkRhdGEiLCJhdXRocG9sIjoiQVRfUEFTQSIsImNoYW5uZWwiOiJDSF9FWFRSQVBQIiwiZGV2aWNlX3R5cGUiOiJEVF9URFNWNCIsImNhbCI6ImFjY2VwdCIsIm1vZGUiOiJ1c2VyaWRfbGVzcyJ9.

Copy

The JWT JSON payload of login_hint_token is:

{
    "tds": "transactionData",
    "authpol": "AT_PASA",
    "channel": "CH_EXTRAPP",
    "device_type": "DT_TDSV4",
    "cal": "accept",
    "mode": "userid_less"
}

Copy

Example of login_hint_token without the optional RMSInfo:

eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfUEFTQSIsInRkcyI6IlBsZWFzZSB2YWxpZGF0ZSBMb2dvbiIsImNoYW5uZWwiOiJDSF9ESVJFQ1QiLCJ1c2VyY29kZSI6Ik15VGVzdFVzZXIiLCJkZXZpY2VpZCI6IjExOTI0IiwiY3JlYXRlU2Vzc2lvbiI6IjAifQ.

Copy

The JWT JSON payload of login_hint_token is:

{
    "authpol":"AT_PASA",
    "tds":"Please validate Logon",
    "channel":"CH_DIRECT",
    "usercode":"MyTestUser",
    "deviceid":"11924",
    "createSession":"0"
}

Copy

Example of login_hint_token for RADIUS Send After:

eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfVERTIiwidGRzIjoidGVzdCByYWRpdXMiLCJjaGFubmVsIjoiQ0hfVlBOIiwidXNlcmNvZGUiOiJzcGwtY3VzdDAyIiwiY3JlYXRlU2Vzc2lvbiI6IjEifQ.

Copy

The JWT JSON payload of login_hint_token is:

{
  "authpol": "AT_TDS",
  "tds": "test radius",
  "channel": "CH_VPN",
  "usercode": "spl-cust02",
  "createSession": "1"
}

Bcauthorize Request (Push Mode Only)

POST https://[base-server-url]/{tenant}/authn/bcauthorize HTTP/1.1
Connection: close
Content-Type: application/json
Authorization: Bearer RTp7HwAAAXk3s41v8uBOEA92yE98qTLB1+SKlONh
 
{
    "scope": "openid hid-tx-sign",
    "acr_values": "mod-mf",
    "client_notification_token": "8d67dc78-7faa-4d41-aabd-67707b374255",
    "login_hint_token": "eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfVERTIiwidGRzIjoie2Ftb3VudCwgNDAwLjAwfSx7c29ydGNvZGUsMjAtMzAtOTB9LCB7YWNjb3VudF90bywxMjM0LTU2Nzh9IiwiY2hhbm5lbCI6IkNIX1REUyIsInVzZXJjb2RlIjoiYmFua3VzZXIwMSIsImRldmljZWlkIjoiMTEwNTgiLCJjcmVhdGVTZXNzaW9uIjoiMSJ9."
}

Where the additional client_notification_token parameter is specific to the push mode and is a token generated by the client application that will allow to authenticate the HID Authentication Service server calling for the notification callback.

Bcauthorize Response

HTTP/1.1 200 OK
Cache-Control: no-store
X-XSS-Protection: 1; mode=block
Pragma: no-cache
X-FRAME-OPTIONS: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 84

{
    "auth_req_id": "6a33b2fc-21d3-4c59-9fe7-9163072aa1c2",
    "txid": "eyJ6aXAiOiJERUYiLCJraWQiOiJLRVkxIiwiY3R5IjoidGV4dFwvcGxhaW4iLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiY29udGFpbmVyaWQiOiI2MSIsInZlcnNpb24iOiJ2OCIsImFsZyI6ImRpciIsImNpZCI6MTExOTl9..Vj1nP-C6ZQZvZYmNBN57iQ.lCMO6ibvDO1U-cEQcDyhSo7mx_ky4rlzpYXdrLF4eBwRmu9swgR9Ln7FrabIJVTL0tVRDx2-HbBcsFd6l8OzurV2UWNI6XiH8qTf3WaKBKU.Ye9A3mRIlZyN2JK5hR4O_IRLcBowVX05d--MJy5CAEw",
    "interval": 5,
    "expires_in": 120
}

Where:

• auth_req_id – is a unique ID (that is, correlationID) generated by HID Authentication Service that identifies the push-based operation in progress

• txid is the HID custom parameter representing the transaction ID in the notification sent to the mobile device by the push delivery adapter. This parameter allows establishing the link between auth-req-id and the txid received by the mobile application.

  txid is the encrypted JWT (JWE) format with the header (in clear):

  Copy

  {
      "zip": "DEF",
      "kid": "KEY1",
      "cty": "text/plain",
      "enc": "A256CBC-HS512",
      "containerid": "61",
      "version": "v8",
      "alg": "dir",
      "cid": 11199
  }

  Where cid is the challenge ID present in all txid headers (although txid can have different values due to the encryption algorithm, initiate vector etc.).

  The challenge ID also corresponds to the server-side challenge and can be used by integrators to retrieve each request (that is, transaction).

  You can also use the HID Approve SDK entry point, Device.retrieveActionInfo(actionId), to get the cid (ServerActionInfo.getUniqueIdentifier()). For further information, go to HID Approve SDK Transaction Signing.

• expires_in – the validity (in seconds) of the logon or operation validation request on HID Authentication Service

Error Responses