CIBA Demo Portal Sample

This sample web application demonstrates the workflow for Client Initiated Back-channel Authentication (CIBA) notifications.

It uses the OpenID and SCIM REST APIs to send an action validation operation to the HID Approve application.

It then waits for the result of the operation validation on its CIBA callback servlet.

  1. The user opens the CIBA Demo Portal application URL in a browser.

  2. The user enters their username and the text of the operation to be validated on the mobile device.

  3. The CIBA Demo Portal application server sends the CIBA authentication request to ActivID Appliance.

    The source for generating this request on the CIBA Demo Portal sample code is provided in SDK\Samples\Push_Authentication_Sample\CIBADemoPortal.zip\Sources\java\com\hidglobal\ia\openid\connect\sdk\

    • CIBAAuthRequest.java
    • CIBAAuthResponse.java

  4. ActivID Appliance sends the push logon request to the user’s mobile device via the notification hub.

  5. The hub forwards the push logon request to HID Approve on the user’s mobile device.

  6. The user approves the logon request using HID Approve on their mobile device.

  7. HID Approve sends the user’s push response to ActivID Appliance.

  8. ActivID Appliance sends feedback of the user’s approval to the CIBA Demo Portal application using CIBA notification (ActivID Appliance sends a CIBA HTTPS request to the CIBA Demo Portal application CIBA callback endpoint).

    The source for parsing this request on the CIBA Demo Portal sample code is provided in:

    SDK\Samples\Push_Authentication_Sample\ CIBADemoPortal.zip\Sources\java\com\hidglobal\sample\controller\

    • CallbackServlet.java

  9. The CIBA Demo Portal application displays the result of the operation validation (APPROVED or DENIED).

Prerequisites:  

  • Your ActivID Appliance system is configured for push-based operation validation using CIBA mode as described in Configure Feedback for External Applications.

  • To deploy this sample application, you need one of the following application servers:

    • Red Hat JBoss EAP 7.1 or later
    • Red Hat WildFly 10.1.0.Final (Windows or Linux) or later
    • IBM WebSphere
    Note: The following procedures are illustrated using Red Hat JBoss.

  • A user with HID Approve installed and registered on a mobile device, ready for push-based authentication.

Install the CIBA Demo Portal Sample

  1. Download the CIBA Demo Sample Package (CIBADemoPortal.zip) available from the ActivID Customer Portal.

  2. Unzip the Push_Authentication_Sample\CIBADemoPortal.zip file to the destination of your choice on your application server.

  3. Follow the installation instructions in the sample's readme file (Readme-CIBA-demo-sample.txt).

The CIBA Demo application is then accessible using http://<YOUR_SERVER>:8080/CIBADemoPortal

For example, when installed locally, http://127.0.0.1:8080/CIBADemoPortal.

Run the CIBA Demo Portal Sample

  1. Go to http://<YOUR_SERVER>:8080/CIBADemoPortal.

  2. In the CIBA Demo Portal, send an operation to myTestUser1:

    CIBA Demo Portal waits for the result by listening on its CIBA callback servlet:

    3. The HID Approve application displays the notification and prompts for validation.

  3. On the HID Approve application, approve the operation.

  4. The result is displayed in the CIBA Demo Portal.

    5. Or

Details of Requests and Source Code

Note: For a complete description of the CIBA flow, go to https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html

The source for generating the requests on the CIBA Demo Portal sample code is provided in:

SDK\Samples\Push_Authentication_Sample\ CIBADemoPortal.zip\Sources\java\com\hidglobal\ia\openid\connect\sdk\

  • CIBAAuthRequest.java

  • CIBAAuthResponse.java

Authentication Request

The following is an example of the creation of a CIBA authentication request using the bcauthorize endpoint.

This request is sent to the ActivID Appliance server by the CIBA demo application to request a push-based logon or operation approval on mobile device.

Copy 
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."
    }

    Where:

    Parameter Description

    usercode

    The ActivID Appliance identifier of the targeted user

    This is not required for userID-less QR code operations.

    deviceid

    The ActivID Appliance 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 ActivID Appliance (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

    The message has a maximum size limit of 1200 characters.

    createSession

    (Optional) Defines if ActivID Appliance 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)

    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 refer to the ActivID Risk Management Service Integration Guideavailable from the ActivID Customer Portal). 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"
    }

Authentication Response

Copy 
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": "a95c61e0-f604-4905-98b1-26b7b87fe073",
    "interval": 5,
    "expires_in": 120
}

Where:

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

  • expires_in – the validity (in seconds) of the logon or operation validation request on ActivID Appliance

HTTP Callback Content

The following is an example of content received by the demo portal application on the HTTP callback.

ActivID Appliance sends the result of approval by calling the demo portal application callback endpoint with the following request:

Copy 
POST CIBADemoPortal/CB/getApprovalStatus HTTP/1.1
Host: https://demohidapp1.server.com:8445
Authorization: Bearer 8d67dc78-7faa-4d41-aabd-67707b374255
Content-Type: application/json                        

{ 
    "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac1",
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJub25lIn0.eyJyZXN1bHQiOjEsInJlYXNvbiI6IlJlYXNvbiBub3QgZGVmaW5lZCIsImRvbWFpbiI6Ik9OTElORUJBTksiLCJKV1MiOiJleUowZVhBaU9pSktWMVFpTENKaGJHY2lPaUpTVXpVeE1pSjkuZXlKamJHbGxiblJoY0hCeWIzWmhiSE4wWVhSMWN5STZJbUZqWTJWd2RDSXNJblJrY3lJNklraGxiR3h2SUcxNVZHVnpkSFZ6WlhKY2JseHVVR3hsWVhObFhHNTJZV3hwWkdGMFpTQjViM1Z5WEc1c2IyZHZiaUJ5WlhGMVpYTjBYRzUwYnlCUGJteHBibVVnUW1GdWEybHVaeUJFWlcxdklpd2lkSGhqYjNWdWRHVnlJam9pTnlKOS5ydHp6NUZqdDhVcjBsZUxYTlNqdFFPdF9kRnd0QVgyUHpzNFdvZTluYUtUc2RrdFUwZjhMS01FNGc4MDE1X0RtZmFQNE16MURhS2FoeVdLbWpwOTNMRlUzM2YzWFVZMk1aZmtWVnNUVEJoTHJWUTlITnZVT0J0QVBHUDhxcFBHeEZ1VFVKLVJjNXdLWHF1WHd0NUE2ZWlBTm9aZ0RYbU5maU1YM09TTDhvbGNMYm1xTEcwc3pZSk41Q0dhSVBWMFhZUlR6N0d0bnlVQmZPeWNpejZJa0RMam94M1NXbUUwZG1Kdi1wQmY1SHJ5dW54M3ctelpfei1aNEgzazJ6MFA0SEZJbjNHYmxhUmw4NzhYTml0M25fOFo2eXlDdTlhZnJXZlhKTmw2aUZPbEZkeFhKM05WVlJscURCRFpZUDE4R0ttOGpMeEdwd0x2dFNxNElQOGFxNEE9PSIsIlBVSyI6Ik1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBTUlJQkNnS0NBUUVBM3phOSs0WUJ3RkZlbVVxR3JcL21VellDcEJmOVo3NDlHSkNLcnB5OVwvaDJlN2ZnRElXXC9ReWptRWdrMjJNV0MyeFpJVlpaYUdrU0QydlNcL3VzM2VQWUlzdmFVbVNVMENCbEM2Uk1IWnFhaldYcHl3MjBXS1pBVmtCZDJnMEVRVjF5ZjY1eEpBMVwvQ3ZtWUlKU0ZEZjdQcTJuTnplU21QZ1U0V1dvYnh6azJIQ2JhTjdlZXA2M3I2RDBCNlpya2ZiSDZNZTRFbVk4WUNQSlhScWRGR2tRNUdSRUhDcnRLQk1WcEZrSExkdFNnV0ZcL21QNVlLZitmbnMwd2pPcURVcExKSGpBNkdlOE54UVpjK2FwdVdRanRqbmVzSU5QSE0yN0pXc1FZd0FDT1FCWEZsM3YzbjFEQ0dxYW5MNDhwWURTdUd5azU4d0xSUDRhdjFLM3NRdXRiVWdRSURBUUFCIiwiY2xpZW50YXBwcm92YWxzdGF0dXMiOiJhY2NlcHQiLCJ1c2VyY29kZSI6Im15VGVzdHVzZXIiLCJkZXZpY2VpZCI6MTI2MTl9. "
}

Where:

  • auth_req_id is the unique ID (aka correlationID) of the approved push-based operation

  • access_token is a the session generated by ActivID Appliance for logon approval

  • id_token can be a Plain JWT (legacy format) or Signed JWT or Signed and Encrypted JWT depending on the configuration (the hid_ciba_callback_format_plain parameter of the OpenID client) with information about the push-based operation approval (user, deviceid, approval status, signed transaction, public key)

    • In the plain format:

      Copy 
      "id_token":
      {
          "result": 1,
          "reason": "Reason not defined",
          "domain": "ONLINEBANK",
          "JWS": "eyJ0eXAiOiJKV1Q...GpwLvtSq4IP8aq4A==",
          "PUK": "MIIBIjANBgkqhki..DAQAB",
          "clientapprovalstatus": "accept",
          "usercode": "myTestuser",
          "deviceid": 12619
      } 

    • In the Signed or Signed and Encrypted format:

      Copy 
      "id_token":
      {
          "at_hash": "J-PJqCh9ahH_GWdl6Z4yOA",
          "sub": "testp2",
          "reason": "Reason not defined",
          "JWS": "eyJ0...6iSniVwEZwRg==",
          "PUK": "MIIB...LRXN0wIDAQAB",
          "iss": "https://server.example.com:8445/idp/ONLINEBANK/authn/token",
          "deviceid": 16711,
          "result": 1,
          "aud": "spl-api",
          "acr": "3",
          "urn:openid:params:jwt:claim:auth_req_id": "b6e6fea7",
          "auth_time": 1589905907,
          "clientapprovalstatus": "accept",
          "exp": 1589909507,
          "iat": 1589905907
      }

    Where:

    • domain is the ActivID Appliance security domain where the device is registered

      In the new ID Token format, the domain is part of the "iss" claim.

    • usercode is the user to who the device is assigned

      In the new ID Token format, the usercode is in the "sub" claim.

    • aud claim contains the client_id of the application that requested the operation
    • deviceid is the ID (in the ActivID Appliance server) of the device being registered
    • result=<1/2>:
      • If result =1, the server has successfully validated message signature response sent by the mobile. In this case, <reason> is not defined
      • If result =2, the message signature cannot be validated by the server. In this case, <reason> provides detailed information about the reason for the failure
      • reason=<failure reason>
    • clientapprovalstatus is the action performed on the mobile device for this operation. It can be accept or deny:
      • If user approved the operation, the Clientapprovalstatus is accept
      • If user declined the operation, the Clientapprovalstatus is deny
    • JWS is the operation data and signature value (JWS parameter in audit)

      For details about the format definition, go to http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-15 or https://bitbucket.org/nimbusds/nimbus-jose-jwt/wiki/Home.

    • PUK is the public key component of the private key used to sign the operation data (PUK parameter in audit)

Note:  

The source for parsing this request on the CIBA Demo Portal sample code is provided in:

SDK\Samples\Push_Authentication_Sample\ CIBADemoPortal.zip\Sources\java\com\hidglobal\sample\controller\

  • CallbackServlet.java