CIBA Demo Portal Sample

This sample web application demonstrates the workflow for 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 AS.

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

    • CIBAAuthRequest.java
    • CIBAAuthResponse.java

  4. ActivID AS 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 AS.

  8. ActivID AS sends feedback of the user’s approval to the CIBA Demo Portal application using CIBA notification (ActivID AS 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_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 AS system is configured for Client Initiated Back-channel Authentication (CIBA) notification callback 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

    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.

Installation

  1. Unzip the Push_Authentication_Sample\CIBADemoPortal.zip file to the destination of your choice.

  2. On your system where you plan to deploy this sample web application, create a base folder for the sample configuration files.

    For example, C:\sample\CIBADemoPortal on Windows or /opt/CIBADemoPortal on Linux, referred to as <SAMPLE_HOME> in the rest of this section.

  3. Copy the config folder from the unzipped delivery to <SAMPLE_HOME>.

  4. Edit the config/configuration.properties file to add your configuration.

    At a minimum, update the following settings:

    • activid.url – the URL of your ActivID AS server (https://<serverhost>:8445).

      • For example, activid.url=https://demohidapp1.activid-as.com:8445

    • activid.domain – the ActivID AS server security domain.

      • For example, activid.domain=ONLINEBANK

    • activid.system.username – the direct user used by this sample to connect to ActivID AS.

      • For example, activid.system.username=spl-api

    • activid.system.password – the direct user password.

      • For example, activid.system.password=password01

  5. Edit the config/log4j.properties file to update <SAMPLE_HOME> with your base folder.

    log4j.appender.CIBADemoPortal.file=<SAMPLE_HOME>/logs/CIBADemoPortal.log

    For example, on Linux where <SAMPLE_HOME> is /WORK/CIBA:

  6. Use the application server console to deploy the CIBADemoPortal.war sample WAR file.

    For example, on a JBoss application server:

    1. Connect to the JBoss administration console and, under Deployments, click Add, and then Upload a new deployment.

    2. Browse to the CIBADemoPortal.war file in the unzipped delivery.

  7. Add your base folder to the application server system properties.

    For example, on a JBoss application server:

    1. Under Configuration, select System Properties.

    2. Add the CIBA_DEMO_PORTAL_HOME property with your <SAMPLE_HOME> as the value.

  8. Trust your ActivID AS server certificate by either:

    • Copying your server truststore (ssl-server.truststore) file to <SAMPLE_HOME>/config.
    • Creating a JKS key store  (for example, ssl-server.truststore) using the root CA certificate of your ActivID AS server and copy this key store to <SAMPLE_HOME>/config.

  9. Add your truststore configuration to the application server system properties.

    For example, on a JBoss application server:

    1. Under Configuration, select System Properties.

    2. Add the following properties:

      • javax.net.ssl.trustStore with the value <SAMPLE_HOME>/config/ssl-server.truststore.
      • javax.net.ssl.trustStorePassword with the value changeit.
      • javax.net.ssl.trustStoreType with the value JKS.

  10. Restart your application server.

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_sample\CIBADemoPortal.zip\ 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 AS 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:

    • usercode – is the ActivID AS identifier of the targeted user.

    • deviceid – is the ActivID AS identifier of the targeted device.

      Optional, if not set then the notification is sent to the last used device (the active device that has the most recently used credential for the authentication policy on request).

    • authpol – is the authentication policy to use.

    • channel – is the channel to create the logon or operation request on the ActivID AS (optional, the default is the channel configured for the OpenID client).

    • tds – is the logon or operation validation message to be displayed on the device for approval.

    • createSession – is the optional parameter to define if ActivID AS 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).

    • RMSInfo (optional) – is 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 Guide available 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 without the optional RMSInfo:

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

Authentication Response

Where:

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

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

HTTP Callback Content

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

ActivID AS 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 AS for logon approval.

  • id_token can be a Plain JWT (legacy format) or Signed JWT or Signed&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&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 AS 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 AS 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_sample\CIBADemoPortal.zip\Sources\java\com\hidglobal\sample\controller\

  • CallbackServlet.java