Customize the Push Solution Behavior

Customize the Key Protection Methods

Keys provisioned on the mobile can be protected by different means. According to the security level required, users might need to enter a password or select a biometric (fingerprint/face) prior to using the keys.

These protection methods will impact how the end user uses mobile keys to:

  • Validate a logon request

  • Validate an action

  • Generate a new Secure Code

Important: If you are using the HID Approve application, do not change the Key protection policy TYPE parameter value in the key’s Credential Type. For all of the Mobile Credential keys (except the Transport key used for Mobile Service), the Container policy is used (see below).

This policy ensures that the user experience is the same for all the mobile operations using the service - either never being prompted for a password/biometric, or being prompted for a single (identical) password.

If you want users to use different passwords, or a different type of protection for each operation, it is recommended that you use the HID Approve SDK.

To customize the Key Protection Method, go to the Device Type and edit the Container keys protection policy according to the following table.

Protection method Behavior

Device-protected

(parameter device)

No prompt for password.

The key is protected by the device transparently.

Password-protected

(parameter password)

Prompt for password.

The key is protected by a password.

When keys provisioned on the mobile are protected by a password, this password is supplied to the HID Approve SDK to unlock the private key to sign a Logon or an Action validation, or to generate a Secure code (as illustrated below).

If an invalid password is entered, the requested signing operation will fail.

Device Lock or Password-protected

(parameter devicelockorpassword)

Prompt for password only if the device does not have a screen lock mechanism configured at the time of the service registration. If it does, there will be no password prompt.

The key is protected by a password.

When keys provisioned on the mobile are protected by a password, this password is supplied to the HID Approve SDK to unlock the private key to sign a Logon or an Action validation, or to generate a Secure code (as illustrated below).

If an invalid password is entered, the requested signing operation will fail.

Biometric-protected or Password-protected

(parameter biometricorpassword)

Prompt for biometric (fingerprint/face).

Prompt for password only if the device does not support biometric authentication (biometric reader unavailable) or a biometric credential has not been enrolled/enabled.

The key is protected by an enrolled biometric or a password.

When keys provisioned on the mobile are protected by a biometric, this biometric is supplied to the HID Approve SDK to unlock the private key to sign a Logon or an Action validation, or to generate a Secure code (as illustrated below).

If an invalid biometric is entered, a password prompt is displayed.

If an invalid password is entered, the requested signing operation will fail.

Container

(parameter container)

The key is protected using the global method configured for the service (one of the above methods, defined in the device type).

Note:
  • The password is set by the user during Service registration.

  • The password to unlock the private keys is the same for all private keys for a particular Service in the HID Approve application.

  • The password can be different from one Service to another.

  • The biometric (fingerprint/face) credential is set independently of the Service registration workflow.

  • Only one biometric (fingerprint/face) credential can be set for Services registered with the application.

Protected Logon Validation

Protected Action Validation

Protected Secure Code

Note: Password Expiration/Changing a Password

If a password has already expired, the user will automatically be prompted to set a new password when they next use the protected service.

Configure the Protection Method per Key

Note: This policy will apply to the key corresponding to this Credential Type. For further details, see Key Protection Policy Parameters.
  1. Log on to the ActivID Management Console as a Configuration Manager.

  2. Select the Configuration tab and, under Polices, select Authentication and then Credential Types.

  3. Select a push-based credential type (that is, Mobile Action Validation Credential or Mobile Logon Validation Credential).

  1. In Credential Adapter tab, specify the Key protection policy – that is, one of the policies listed in Protection method.

Configure the Protection Method for All Keys

Note: This policy will apply to all keys for this Service if the keys' individual protection parameter is set to TYPE=container. For further details, see Key Protection Policy Parameters.
  1. Log on to the ActivID Management Console as a Configuration Manager.

  2. Select the Configuration tab and, under Polices, select Authentication and then Device Types.

  3. Select the Mobile push based Validation Device type.

  4. Select the Device Adapter tab.

  5. Specify the Container keys protection policy – that is, one of the policies listed in Protection method.

  6. Click Save.

Customize the Secure Code Settings

The Secure Code can be configured by editing the Credential Type. For further information, see OTP Key Parameters (Secure Code).

Secure Code Settings for One-Time Password (OTP)

Parameter Values

Algorithm mode

  • Event (Default value)
  • Time

OTP length

  • 4 digits
  • 6 digits
  • 8 digits

Secure Code Settings for Challenge/Response

Parameter Values

Algorithm mode

  • Event (Default value)
  • Time

Challenge length

  • 4 digits
  • 6 digits
  • 8 digits

Secure Code Settings for Signature

Parameter Values

Algorithm mode

  • Event (Default value)
  • Time

Customize the Application Password Caching Mode

The HID Approve application allows the Service Protection to be kept in cache during the handling of the Push operations.

For the password caching policy parameters, see Key Protection Policy Parameters.

Customize the Maximum Number of Devices Allowed per User

You can restrict the number of devices a user can register (per ActivID AS domain) for the push solution.

This value can be set in the Maximum Number of Devices per user parameter of the Mobile push based Validation device type (DT_TDSV4).

Note: For further details about the device type parameters, see Device Type Common Parameters.
  • If you do not define a restriction (that is, keep the default value of -1), the user can register services on an unlimited number of devices with the HID Approve application.

  • If you define a restriction, when the user reaches the maximum number of allowed devices and attempts to register a service on a new device, they will see an error message in the registration portal.

Customize the Devices Allowed for Service Registration

The HID Approve application allows defining a set of rules restricting the service registration according to the mobile platform characteristics.

You can exclude platforms from Service registration based on the following:

  • Specific OS (Android or iOS)

  • Specific OS version or a range of versions (by defining the maximum and minimum values)

  • Specific key store mode (software or hardware)

  • Specific root state (corresponding to a rooted Android phone or a jailbroken iOS phone)

When a platform is excluded, a warning is displayed during service registration on the user’s device. This warning can be customized on the server-side.

The "rules" are defined using the following JSON payload for the "provisioning" claim:

  • "ruleid" – an ID to identify the rule. Several rules can be added in the JSON (for example, one per outcome).

  • "phonestates" – a list of mobile platform characteristics containing of one or several of the following:

    • "os" – defines the OS platform (that is, Android or iOS)
    • "osversion" – defines the OS platform
    • "keystore" – defines the key store mode (either sw for software or hw for hardware)
    • "isRooted" – defines the rooted/jailbroken state of the device (either true or false)
    • "maxosversion" – defines the maximum value of the range of OS versions
    • "minosversion" – defines the minimum value of the range of OS versions
  • "outcome" – defines the result of the rule:

    • deny - provisioning is denied for the device

  • "Message" – a customizable warning message displayed to the user when the rule is applied

For Android devices only, it is also possible to define authentication rules to restrict biometric authenticators. If the rule is not defined, by default, only strong (class 3) biometric authenticators are authorized. The rules are defined using the following JSON payload for the "authentication" claim:

  • "ruleid" – an ID to identify the rule

  • "bioclass" – an integer value of 2 or 3 corresponding to the minimum authorized biometric class security level

  • "outcome" – to define the result of the rule

    • Only allow is currently supported

For example, JSON data with two rules and one authentication rule to allow class 2 biometrics:

Copy

HID Approve Rules Parameters

"rules": {
	"version": 1,
	"provisioning": [
		{
			"ruleid": 1,
			"phonestates": [
				{
					"os": "Android",
					"osversion": "6",
					"isRooted": "true"
				},
				{
					"os": "Android",
					"keystore": "sw"
				}
			],
			"outcome": "deny",
			"message": "Not allowed to provision for Android version 6 rooted phone or Android device with software key store"
		},
		{
			"ruleid": 2,
			"phonestates": [
				{
					"os": "iOS",
					"maxosversion": "10",
					"minosversion": "9"
				}
			],
			"outcome": "deny",
			"message": "Not allowed to provision for iOS version 9 to 10 "
		}
	],
	"authentication":[
		{
			"ruleid":3,
			"bioclass":2,
			"outcome":"allow"
		}
	]
}

To apply the defined rules:

  1. Log on to the ActivID Management Console as a Configuration Manager.

  2. Select the Configuration tab and, Under Polices, select Authentication and then Device Types.

  3. Select the Mobile push based Validation Device type (DT_TDSV4).

  4. Paste the JSON content into the Policy Rules field and save your changes.

Alternatively, you can apply the rules by adding your definitions in the policyRule parameter using the Device Type REST API.

Note: For further details about the device type parameters, see Device Type Common Parameters.

Customize the HID Approve Windows Universal App Activation Link (URI)

For the HID Approve Windows Universal App, a URI can be used to automatically start a service registration from a web page. It can be customized as follows:

Prerequisites: The HID Approve Windows Universal App is installed on the tablet/PC on which the end user is accessing the web portal.

The URI must respect the following syntax:

Copy
hidglobal-approve://activate?name={AppName}&qrcode={ ActivationCode }

Where:

{AppName}

  • Is part of a mandatory query

  • Is the web application friendly name that will be displayed to the user (maximum of 30 characters, and can contain only letters, numbers, spaces and dashes)

  • Format is percent-encoding UTF-8 based

{ ActivationCode }

  • Is part of a mandatory query

  • Is the activation code that will be used to register a new service for the user (maximum of 1000 characters)

  • Format is base64 encoding

Customize Multiple Device Types

Multiple device types can be configured on ActivID AS to allow different branding or policy settings on a single Security Domain.

You can customize Device Types to meet your requirements, taking into consideration that:

  • Each device type can use a specific Customization file (allowing a different look and feel within the same domain).
  • When several device types co-exist in a domain, the registration portals must reflect the possible choices to allow registering services for one or the other.
Note: Users cannot register more than one service from a domain on a single device (even if they target different device types). HID Approve application will always keep the latest registered service as the only one. Users should use different devices in this particular case.

See also:

Customize the HID Approve Application

Request-device-registration Samples

Key Protection Configuration Best Practices