Request Formats

Device Issuance Request Format

The bank application requests the registration of a device using the ActivID SCIM API 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:

  • did=<deviceid> (device ID attribute of device created by bank application for this registration).

  • url=<HostName of ActivID AS Server>:<Port of ActivID AD Server URL>/<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 request-device-activation-sample\sources\java\com\hidglobal\sample\RequestDeviceProvision.java

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 ActivID SCIM API "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 deviceid 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 (request-operation-validation-sample\sources\java\com\hidglobal\sample\DeliverChallenge.java):

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);