Request Formats

Device Issuance Request Format

The bank application requests the registration of a device using the Device/Provision endpoint (POST method):

The registration request creation process requires specific information that must be part of the request. The description field in DeviceIssuanceRequest is used to pass this information.

The description field format is a string composed of the following list of parameters, separated by commas:

Parameter Description
did <deviceid> (device ID attribute of device created by bank application for this registration)
url <HostName of ActivID AS Server>:<Port>/<Security Domain>
sec <provisioning password> empty (secret generated byActivID AS)
pch (optional) Channel code of the channel used by the HID Approve application for registration
pth (optional) Authentication policy code of the authentication policy used by the HID Approve application for registration
pct (optional) Credential code of the channel used by the HID Approve application for registration
pdt (optional) Device type code of the virtual device used by the HID Approve application for registration
cb_url (optional) HTTP callback URL used by ActivID AS to notify the registration of the device
cb_notif_token (optional) Client notification token to be used by ActivID AS to notify the registration of the device

An example of the description field used by a bank application to call Device/Provision endpoint (minimal value without optional components):

Copy 
did=11352,url= myServer:8445/ONLINEBANK, sec=

Example of registration information returned by Device/Provision endpoint call:

Copy 
{
    "ver":"v7",
    "url" : myserver:8445/ ONLINEBANK,
    "uid": "user1",          
    "did": "11352",           
    "dty”:”DT_TDSV4”,
    "pch":"CH_TDSPROV",
    "pth":"AT_TDSOOB",
    "sec": "",        
    "pss": "cCpNICFdKldpeA=="
}

The following is a code extract of RequestDeviceProvision.java (from the ActivID AS samples in the delivery):

Copy 
logger.trace("Creating device issuance request...");
        DeviceProvision deviceIssuanceRequest = new DeviceProvision();
        Attribute owner = new Attribute(user.getId());
        deviceIssuanceRequest.setOwner(owner);
        deviceIssuanceRequest.setDeviceType(device.getType());
        com.hidglobal.ia.scim.ftress.Attribute authType = new com.hidglobal.ia.scim.ftress.Attribute();
        authType.setName("AUTH_TYPE");
        authType.setValue(Configuration.userAuthType);
        deviceIssuanceRequest.setAttributes(Arrays.asList(new com.hidglobal.ia.scim.ftress.Attribute[] { authType }));
 
        String notes = "did=" + device.getId();
        notes += ",url=" + Configuration.prov_url;
        if(Configuration.prov_channel!=null) // else default values will be used
        {
            notes += ",pch=" + Configuration.prov_channel;
            notes += ",pth=" + Configuration.prov_authtype;
            notes += ",pct=" + Configuration.prov_credentialType;
            notes += ",pdt=" + Configuration.prov_deviceType;
        }
 
        notes += ",sec=";  // Secret is generated by ActivID AS server
 
        deviceIssuanceRequest.setDescription(notes);
 
        DeviceProvision result = null;
        try {
            result = provMng.create(deviceIssuanceRequest);
            
            String id = result.getId();
            if (id == null || id.equals("")) {
                throw new Exception("device issuance request was not created properly");
            }
                        logger.trace("Issuance request created.");
        }
        catch (Exception e) {
            logger.error("Create device issuance request failed: " + e);        }

Operation (Logon/Action) Validation Request Format

The bank application requests operation validation using the Authenticator endpoint (POST method with action= DELIVER-CHALLENGE):

  • Action Attribute tds – message to be displayed on the device for approval

  • Action Attribute correlationid – an ID given by the bank application for this operation

    Allows the bank application to correlate the result of the approval on device (this id is notified back by ActivID AS posting the result of the device approval on JMS topic notification).

  • Action Attribute DEVICE.ID – ActivID AS device ID 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).

  • Action Attribute createSession is (optional "0" or "1")

    Optional, if set to "1", then ActivID AS will create a sessionid (aka ALSI) if operation is validated on the device. Default is "0" where no session is created.

The following is sample code for the validation request operation from DeliverChallenge.java (from the ActivID AS samples in the delivery):

Copy 
 private static void deliverChallenge()
            throws AuthorizationException, ResourceNotFoundException, ClientException, ServerException {
        AuthenticatorManager authMgr = factory.getAuthenticatorManager();
 
        Authenticator authenticator = new Authenticator();
        List<Attribute> attributes = new ArrayList<Attribute>();
 
        // set authenticator id
        authenticator.setId(user_id + "." + auth_type_code);
 
        Action action = new Action();
        action.setAction("DELIVER-CHALLENGE");
 
        // AuthenticationRequestParameter
        Attribute attr = new Attribute("tds", transaction);
        attributes.add(attr);
 
        Attribute attr = new Attribute("createSession", “0”);
        attributes.add(attr);
 
        attr = new Attribute("correlationid", correlation_id);
        attributes.add(attr);
 
        // deviceSearchCriteria
        attr = new Attribute("DEVICE.ID", device_id);
        attributes.add(attr);
 
        action.setAttributes(attributes);
        authenticator.setAction(action);
 
        // call to scim
        authMgr.action(authenticator);