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 Appliance Customization package from the ActivID Console

You then upload the modified template to apply your customization.

1. Log on to the ActivID Console and, under Configuration, select Customization.



2. Under Customization, click Download Package.

3. Save the package to the required location.

4. Unzip the package making sure that you keep the original structure.

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

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



The template below illustrates the parameters and features that you can customize:

• Cosmetic parameters to customize the look and feel
• Transaction Signature fields
• QR code scanning
• ‘Contact’ menu information
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.

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

7. 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

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

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.

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 (QR Code) scanning to capture the OCRA-based Challenge or transaction data.

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

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 Appliance) 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.

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 Appliance (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.
   Computing the "pin" values

   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

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

Apply the Customization Package

1. Log on to the ActivID Console and, under Configuration, select Customization.



2. Browse to your customization page and click Upload.

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

4. Edit the Mobile push based Validation Device Type.



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

6. 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.

See also:

Customize the Push Solution Behavior