Customize the HID Approve Application

You can customize the features and design of the HID Approve application by creating a customized JSON file.

You can also customize several push-based features such as the key protection methods.

Create the Customization Package

To help you customize the application, a template is available by downloading the ActivID AS Customization package.

You then upload the modified template to apply your customization.

  1. Create a customization package by running the following script as ftadmin:

    Copy 
    <ACTIVID_HOME>/ActivID_AS/bin/customizeApplications.sh –c <Output folder>

    Where:

    • -c is the flag to use for the creation of the customization package.
    • <Output folder> is the path to the folder where the customization package will be created.

    2. The package is generated as a .zip file called ActivID_AS_Customization_<CreationDate>.zip where <CreationDate> is the package creation date and time in the format YYYY-MM-dd_HH-mm.

  1. Make a copy of this .zip file on your local disk and open it for editing, making sure that you keep the original structure.

  2. Copy the HID_Approve_Customization_Template.json file from the \default\mobile-app\ folder of the package to the _common_\mobile-app folder.

    3. Note: You can rename or duplicate this file using different filenames to customize each domain. For example, yourcustofiledomain1.json, yourcustofiledomain2.json, yourcustofiledomain3.json, etc).

    This template (as illustrated in the example below) includes the parameters and features that you customize:

    Copy

    HID Approve Customization JSON

    {
	"appcustomization": {
		"uicustomization": {
			"version": 1,
			"label": {
				"id": "1",
				"value": "Development Bank"
			},
			"color": {
				"id": "2",
				"value": "#032569"
			},
			"bitmap": {
				"id": "3",
				"value": " /9O/znDIq1z3el3lpL7WU/ +fWPmc89pnK945r32uVe GQxM2QwN2NlZDU3NWViMzA4MmFiODE3NTY3jE92bu3V4/mUl/Tp8f372nuo3Y/GQxM2QwN2NlZDU3NWViMzA4MmFiODE3NTY3"
			},
			"fontcolor": {
				"id": "4",
				"value": "#02597F"
			},
			"ocrafields": [
				{
					"label": {
						"id": "5",
						"value": "AccountId"
					}
				},
				{
					"label": {
						"id": "6",
						"value": "Date"
					}
				},
				{
					"label": {
						"id": "7",
						"value": "Amount"
					}
				}
			],
			"ocraallowscan": true
		},
		"contactdetails": {
			"phonenumber": "+33612345678",
			"email": {
				"address": "user@hidglobal.com",
				"subject": "Message from {$userid} for {$service}"
			},
			"website": "https://www.hidglobal.com",
			"deviceid": true,
			"devicesn": true
		}
	}
}
    Note: To avoid configuration errors, the above sample does not include the Certificate pinning section. For further information, see Customize the Application Certificate Pinning Behavior.

  1. Customize the .json file properties as required and save the file.

  2. Apply your customization package.

Customize the Application Look and Feel per Service

The HID Approve application allows the Service Provider to customize the look and feel of the application. Each Service Provider can use a:

  • Service label

  • Service background color

  • Bitmap image (logo) that will serve as a graphical representation of the service

  • Font color of the text/label

Note: If the app is not customized, the HID Global branding (as illustrated above) is used where the default values are:

  • Service name – HID Global

  • Background color – #084586

  • Logo – the HID logo (base64-encoded)

  • Text/label color – #FFFFFF (white)

  1. Select an image to use and encode it in base64 (using a tool such as http://www.motobit.com/util/base64-decoder-encoder.asp).

    2. Important: The maximum size allowed for the customized icon image is 400 x 400 pixels.

  2. Build a JSON file (or make a copy of the template downloaded in the Customization Package) and add the id and value pairs of your customized design in the ""uicustomization section:

    • "label" - the Service name as a text value
      • Important: The maximum length allowed for the Service name is 50 characters. Names that exceed this limit will be truncated by the HID Approve application.
    • "color" - the background color as an HTML color value
    • "bitmap" - the logo as a .png file (base64-encoded)
    • "fontcolor" - the color of the text/label as an HTML color value
    Note:
    • You are not required to customize each item. If an item is not defined or incorrectly configured, the default values will be used. However, if you define a custom background or font color, make sure the color selection renders the service label readable.

    • The "version" value cannot be customized. This field is reserved for future use.

    3. For example:

    Copy

    HID Approve Look and Feel Parameters

    {
	"appcustomization": {
		"uicustomization": {
			"version": 1,
			"label": {
				"id": "1",
				"value": "<label-value>"
			},
			"color": {
				"id": "2",
				"value": "<color-value>"
			},
			"bitmap": {
				"id": "3",
				"value": "<bitmap-value-base64>"
			},
			"fontcolor": {
				"id": "4",
				"value": "<color-value>"
			}
		}
	}
}

  3. If the file contains non-ASCII characters, encode it in UTF-8 (so all text characters will be displayed correctly).

  4. Save the customized file.

  5. Apply your customization package.

Customize the Transaction Signature Fields

The HID Approve application must be updated to specify the OCRA transaction signature fields to be displayed on the user’s screen.

  1. Build a JSON file (or make a copy of the template in the Customization Package) containing a sub-section, specifying the id and value pairs of the "label" for the required fields in the "ocrafields" section.

    For example:

    Copy

    HID Approve Transaction Signature Field Parameters

    {
	"appcustomization": {
		"uicustomization": {
			"ocrafields": [
				{
					"label": {
						"id": "5",
						"value": "AccountId"
					}
				},
				{
					"label": {
						"id": "6",
						"value": "Date"
					}
				},
				{
					"label": {
						"id": "7",
						"value": "Amount"
					}
				}
			]
		}
	}
}

  2. If the file contains non-ASCII characters, encode it in UTF-8 (so all text characters will be displayed correctly).

  3. Save the customized file.

  4. Apply your customization package.

Customize the Capture Mode to Enable QR Code Scanning

The HID Approve application must be updated to enable Quick Response Code (QRCode) scanning to capture the OCRA-based Challenge or transaction data.

HID Approve can capture the details of a multi-parameter OCRA transaction via a QR code scan.

This requires formatting the string (to encode the QR) with the correct syntax, and the ocrafields id tags must correspond to the identifiers (id) of the "label" pairs defined for the ocrafields section in the customization JSON.

The data is encoded using simplified format of unordered UTF-8 key/value pairs.

The expected syntax is:

Copy 
ocra://TAG1:VALUE1;TAG2:VALUE2;TAGn:VALUEn;;

Where:

  • Prefix is ocra://
  • Literal delimiter characters within the tag or value strings are escaped with a backslash ( \ )
  • Tag/values are separated by a colon ( : )
  • Fields are separated by one semicolon ( ; )
  • Closing characters are a double semicolon ( ;; )

Supported Tag values:

Tag Value
S serviceUrl + & + userId
C Challenge value
ocrafields id Signature field value

Example of a Signature QR Code:

Copy 
ocra://S:myservice.com\:443\\DOMAIN&user;5:Account\:123;6:30-11-2020;7:$100;;

Example of a Challenge/Response QR Code:

Copy 
ocra://S:myservice.com\:443\\DOMAIN&user;C:1234567;;

Note: This feature is available with all versions of ActivID AS.

  1. Build a JSON file (or make a copy of the template in the Customization Package) containing a sub-section, setting the "ocraallowscan" feature to true in the ""uicustomization section.

    For example:

    Copy

    HID Approve QR Code Parameter

    {
	"appcustomization": {
		"uicustomization": {
			"version": 1,
			"ocraallowscan": true
		}
	}
}

  2. If the file contains non-ASCII characters, encode it in UTF-8 (so all text characters will be displayed correctly).

  3. Save the customized file.

  4. Apply your customization package.

Customize the Contact Information

You can add the optional ‘Contact’ menu feature and customize the contact information, allowing end users to request assistance or information for the relevant service.

Android

macOS

Windows 10

Note:  

  • The ‘Contact’ option will only be displayed if the HID Approve JSON customization package includes the required configuration for one of more of the contact methods.

  • Only the correctly configured contact methods will be available in the Contact menu. For example, if the customization package includes details for contact via email but not details by phone or website, then only the email contact method will be displayed.

  • In this version, the contact details are not localizable.

  • The user can return to the HID Approve app using the ‘back’ control in the top left hand corner of the screen

Phone number

When the user taps the ‘Phone’ Contact option, HID Approve invokes the device’s dialer app (or prompts to select an app if more than one is detected) and pre-fills the phone number with that defined by the customization package.

Android

iOS

        

When the call is terminated, or if the user cancels the call, they are redirected back to the HID Approve Contact screen.

Email address

When the user taps the ‘Email’ Contact option, HID Approve invokes the device’s default email client (or prompts to select an app if more than one is detected) and populates the email address, email subject, and email message body.

HID Approve adds diagnostic information to the email body and the user can add any additional content to the message.

The diagnostic information includes:

  • Device details such as manufacturer, model, OS and OS version
  • HID Approve app details such as version (and build number) and PushID

Android

iOS

         

When the email is sent, or the user cancels the email, the user must use the device's functionality to return to the previous application (that is, HID Approve).

Website

When the user taps the ‘Web’ Contact option, HID Approve invokes the device’s default browser (or prompts to select a browser if more than one is detected) and redirects the user to the URL defined by the customization package.

Android

iOS

    

Device Information

You can configure the Contact menu to display the user's unique device ID (specific to ActivID AS) and/or device serial number.

This feature can be helpful in customer environments where service desk operators might prefer to search for users by their device serial numbers or IDs during requests for assistance and troubleshooting. This feature is disabled by default.

Note: This feature is only available for HID Approve for Google Android and Apple iOS and macOS.

  1. Build a JSON file (or make a copy of the template in the Customization Package) and add a section called "contactdetails" with the following parameters and your customized values:

    Copy

    HID Approve Contact Parameters

    {
	"appcustomization": {
		"contactdetails": {
			"phonenumber": "+33612345678",
			"email": {
				"address": "user@hidglobal.com",
				"subject": "Message from {$userid} for {$service}"
			},
			"website": "https://www.hidglobal.com",
			"deviceid": true,
			"devicesn": true
		}
	}
}
    Note: You cannot customize the labels for the parameters (for example, “telephone” instead of “phonenumber”. You must keep the default labels.
    • "phonenumber" – enter the contact telephone number including country and area codes.

      • All standard telephone numbers are supported and they can include “+” or ”()” prefixes.

    • "email" – for contact via email:
      • "address" – enter the full email address.

        • If the email address is incorrectly formatted, HID Approve will ignore the contact option.

      • "subject" – enter the default subject for the email message.

        • The {$userid} and {$service} values are retrieved by the application or you can enter static text values.

    • "website" – enter the URL for the website or page.

      • The URL must include the https:// prefix.

  2. Optionally, you can add the following to parameters to display the device information:

    • Include and set the "deviceid" parameter to true so the device ID can be used to find the user during a Quick Search or Advanced Search.
    • Include and set the "devicesn" parameter to true so the device serial number can be used to find the user during an Advanced Search.
  3. If the file contains non-ASCII characters, encode it in UTF-8 (so all text characters will be displayed correctly).

  4. Save the customized file.

  5. Apply your customization package.

Customize the Application Certificate Pinning Behavior

The certificate pinning mechanism uses the ActivID AS (or Reverse Proxy) public key pins to enforce that HID Approve only communicates with the server (or Reverse Proxy) that perfectly matches the TLS information stored during Service registration.

If the values do not match, the connection will be refused and the operation will fail.

Certificate pinning is used in the following operations:

  • Retrieve transaction details

  • Delete the service

  • Device information update (that is, the Push ID)

  • Customization update (that is, the look and feel or new public key pins for an upcoming Server Certificate renewal)

For further information, go to https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning.

This option is not available by default and it can be added as follows:

  1. Build a JSON file (or make a copy of the template downloaded in the Customization Package) and add the "public-key-pins" section with the following parameters and your customized values:

    • "max-age" - defines the validity (in seconds) of the listed certificate pins

      After this period, the listed certificate hashes are considered invalid and new ones must requested by the application. The default and recommended value is 1296000 seconds (15 days).

    • "known-pins" – list of certificate pins and the array must contain two entries, each containing:
      • "alg" - the value of the hash algorithm used (that is, SHA256).
      • "pin" - the certificate pin value which is the Certificate Subject Public key computed hash (base64-encoded).

        The two entries correspond the current and new certificates and it is recommended that you maintain this configuration for each certificate renewal.

        You can use the same "pin" value in the two entries listed in "known-pins".

        However, NIST recommends that system owners maintain the ability to replace all certificates on their systems within two days to respond to security incidents such as CA compromise, vulnerable algorithms, or cryptographic library bugs. To do so, you could have a valid backup certificate from a different CA.

      For example:

      Copy

      HID Approve Certificate Pinning Parameters

      {
	"appcustomization": {
		"public-key-pins": {
			"max-age": 60,
			"known-pins": [
				{
					"alg": "sha256",
					"pin": "<current-cert-pin-value-base64>"
				},
				{
					"alg": "sha256",
					"pin": "<new-cert-pin-value-base64>"
				}
			]
		}
	}
}
      Important: Certificate Rollover Guidelines

      You must anticipate the rollover timing of the proxy SSL certificates.

      At a minimum, it is recommended issuing the new certificate and add its "pin" value to the Customization file before the expiration of the current certificate. You should do so at least "max-age" x2 or "max-age" x3 before the certificate expiration date to avoid service disruption.

      Note: The user must launch the HID Approve app at least once during the rollover period to update the certificate pinning data and avoid service disruption.

      • To compute the Certificate Subject Public "pin" value, the following examples use openssl (https://www.openssl.org/):

      • For a DER-encoded certificate file (for example, <cert-path> = <path>/my-certificate.der):

        Copy 
        openssl x509 -inform DER -in <cert-path> -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -r | sed "s/\([0-9a-f]*\) \*stdin/\1/" | tr -d "\n" | openssl enc -base64

      • For certificate files (for example, <cert-path> = <path>/my-certificate.crt or <path>/my-certificate.cer):

        Copy 
        openssl x509 -in <cert-path> -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -r | sed "s/\([0-9a-f]*\) \*stdin/\1/" | tr -d "\n" | openssl enc -base64

      The output is the base64 value to use for Certificate public key pin value.

  2. If the file contains non-ASCII characters, encode it in UTF-8 (so all text characters will be displayed correctly).

  3. Save the customized file.

  4. Apply your customization package.

Customize the Credential Expiration Warnings

Important: The Service Key Renewal feature is now available to all end users upgrading to HID Approve for iOS and Android 5.1 (or later) or for Windows 4.5 (or later). It is also available with HID Approve for macOS 5.6 (or later). It provides a smooth user experience to help users avoid key expiration.

For users who have not yet upgraded to the latest version of HID Approve, the Credential Expiration Warnings can be added to the HID Approve application.

This legacy option is available for earlier versions of HID Approve and it displays warning messages to users regarding credential expiration. However, it does not allow the actual renewal of the Service keys as users must delete and re-register their service to actually renew the keys.

As this option is not enabled by default, it can be enabled as follows:

  1. Build a JSON file (or make a copy of the template downloaded in the Customization Package) and add a section called "legacywarnings" with the following item and set the value to "on".

    Copy

    HID Approve Expiration Parameter

    {
	"appcustomization": {
		" legacywarnings ": "on"
	}
}
  2. To disable the legacy warnings, set the value to "off".

  3. Save the customized file.

  4. Apply your customization package.

Once the option is enabled, when the user starts the application and if a service has keys that are about to expire, or that have already expired:

  • A global status message is displayed, summarizing the expiration status. If there are several services, several messages will be displayed, one after the other.

  • If the users has multiple services, a warning icon is displayed next to the Service name:

    • A yellow icon indicates that the key is about to expire.
    • A red icon indicates that the key has already expired.

  • For keys that are about to expire:

    • A status message is displayed in the active screens of the service (Secure Code, Challenge/Response or Signature).
    • The message displays the remaining validity period in hours or days (if above 24h) for the credential.

  • For keys that have already expired, a status message is displayed when the user selects the service or a notification for the service.

Note: In all cases, the user could still use the keys (that is, generate an OTP,...) although the authentication request will be rejected as it is no longer valid.

Apply the Customization Package

  1. Apply the updated customization package using the following script:
Copy 
<ACTIVID_HOME>/ActivID_AS/bin/customizeApplications.sh <option> <package file path>

Where:

  • <option> indicates how the customization package is applied:
    • -uf – to apply the full package
    • -uc – to apply only the configuration files
    • -ub – to apply only the branding files
  • <package file path> is the path to the customization package file to apply

  1. Log on to the ActivID Management Console, select the Configuration tab and then, under Policies, select Device Types.

  2. Edit the Mobile push based Validation Device Type.

  3. In the Device Adapter tab, specify the name of the JSON file (in this example, mycustofile.json) in Container UI Customization file field.

  4. Click Save.

Alternatively, you can apply the customization file (encoded in base64 using a tool such as http://www.motobit.com/util/base64-decoder-encoder.asp) with the Device Type REST API.

Note: To apply the customization to existing HID Approve applications (registered on devices), the application must be restarted twice after the certificate pins have been renewed (defined by the value of the max-age parameter).

See also:

Customize the Push Solution Behavior