Advanced Configuration for Push Authentication

The following sections detail the advanced parameters of the push-based validation solution.

These parameters can be edited using the ActivID Management Console:

Important: The parameters highlighted in gray should not be modified.

Device Type Common Parameters

Parameter Description Default Value

Maximum Number of Devices per User [integer]

(API: maximumDevicePerUser)

The maximum number of this type of device that can be assigned to a user.

The limit is only verified when the user attempts to activate a new device of this type and an error message is displayed if they have already reached the maximum.

If you set a maximum, it will not affect users who already have more devices than the limit (that is, it will not block authentication nor delete or modify existing devices). However, these users will only be able to activate a new device if they discard existing devices to meet the new limit. For example, if you set the limit to 2 devices, a user with 3 existing devices will need to discard 2 to activate a new device.

The default value is -1 (unlimited).

URL for operation validation

(API: urlOperationValidation)

URL used to communicate with the application for Logon or Action validation

https://<server>:<port>

Configure with the public URL of your ActivID Appliance. Mobile devices must be able to reach this URL from public network.

For example, if your authentication server is publicly available as myServerHostName on default port 443 then set this parameter as

https://myServerHostName

Important: If a reverse proxy is used to access the ActivID Appliance, make sure that you have configured the proxy server URL (NOT the ActivID Appliance internal URL value).

Server TLS certificate

(API: serverTLSCertificate)

Server TLS certificate complete value used by the device and ActivID Appliance to compute the session key. It corresponds to the body of the ActivID Appliance TLS certificate.

This value can be obtained by viewing the certificate file with Notepad.

This parameter supports configuration of multiple certificates (in PEM format) if your deployment includes multiple access points for HID Approve. Append the certificates such as:

-----BEGIN CERTIFICATE-----
MIIDSzCCAjOgAwIBAgIEco0o3jANBgkqhkiG9w0BAQsFADBWMRYwFAYDVQQLEw1B
...
ax0oW532uDwEQKUpTOIhRjEbP6p8uhyPG4dyV46tPA==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDfDCCAmSgAwIBAgIJAKHzwx0jDzrsMA0GCSqGSIb3DQEBCwUAMCcxJTAjBgNV
...
5F6PlD4k5Q9hBUKFdbO5wxc6R9cENfoEoZVnvtwCmbo=
-----END CERTIFICATE-----

Retrieve the SSL certificate of the authentication server (connecting with a browser) and save it as PEM BASE 64 encoded (for example, as myserverSSLcertificate.crt).

Then edit this file with Notepad and copy the content, including the -----BEGIN CERTIFICATE----- & -----END CERTIFICATE----- mentions.

Important: If a reverse proxy is used to access the ActivID Appliance, make sure that you have configured the proxy server TLS certificate (NOT the ActivID Appliance SSL certificate value).

Container Profile

(API: containerProfile)

Defines the list of credentials and authenticators to generate during registration, as well as the mapping between each authentication policy and its channel, separated by |

Each item uses the format:

type:credential_type:authentication_policy:channel

Each key definition is an array containing:

  • keyType - the type of the key (SMK, OTP or RSA)

  • keyId - the key identifier for the HID Approve application

  • credId - the code of the credential type to associate with this key

  • authPolicyCode - the code of the authentication policy to create for this key and used by HID Approve when performing the transaction signature

  • channelCode - the code of the channel to be used by HID Approve when performing the transaction signature

Important: The first key in the list must always be an SMK key.
Note: To use Event-based credentials for Secure Code versus Time-based credentials, make sure that you update the OTP credential accordingly.

The default value is:

  • Key 1: Credential (AES Key) used for Mobile Service communications
    One CT_SMKV4 credential (SMK) associated with a:

    • AT_SMK authenticator

    • CH_SMK channel

  • Key 2: OATH Time-based credential (secret key) used to generate Secure Codes
    One CT_TDSOT credential (OTP) associated with a:

    • AT_CUSTOTP authenticator

    • CH_PASA channel

  • Key 3: Single-parameter Challenge/Response authentication
    One CT_TDSOATCR credential (OTP) associated with a:

    • AT_CUSTOTP authenticator

    • CH_PASA channel

  • Key 4: Multi-parameter Challenge/Response authentication
    One CT_TDSOATSIGN credential (OTP) associated with a:

    • AT_CUSTOTP authenticator

    • CH_PASA channel

  • Key 5: Credential (RSA key) used during the Logon validation process
    One CT_PASAV4 credential (RSA) associated with a:

    • AT_PASA authenticator

    • CH_PASA channel

  • Key 6: Credential (RSA key) used during Action validation process
    One CT_TDSV4 credential (RSA) associated with a:

    • AT_TDS authenticator

    • CH_TDS channel

Container UI Customization file

(API: custoFile)

Defines the customization file used for the application, and as well the server public key pins used for the certificate pinning mechanism.

See Customizing the Solution.

<empty>

Policy Rules

(API: policyRules)

Rules that define mobile device characteristics (such as OS, OS version, key store mode or rooted state), allowing to excluded matching devices from Service Registration.

Note: The refreshinterval parameter is not supported by HID Approve.
"rules": {
	"refreshinterval": 1440,
	"version": 1,	
	"provisioning": [{
		"ruleid": 1,
		"phonestates": [
			{ 
				"isRooted": "true"
			}
		],
	"outcome": "deny",
	"message": "Not allowed to provision for rooted or jailbroken devices"
	}]
}						

Container keys protection policy

(API: keysProtectionPolicy)

See Key Protection Policy Parameters.

Container transaction history

(API: transactionHistory)

Defines the behavior of HID Approve application for operation (that is, Logon/Action validations) history.

None (do not modify)

Note: The device validity is computed automatically and corresponds to the duration of the minimum value of Key validity period (days) of the credential type keys (CT_SMKV4, CT_PASAV4 and CT_TDSV4).

Device Type Provisioning Protocol

In the ActivID Management Console Configuration tab – under Policies, Authentication, then Device Types.

Parameter Description Default Value

VERSION

(API: version)

Defines the minimum version of the provisioning protocol supported by the server.

v5 (do not modify)

TYPE

(API: type)

Type of registration process:

pki.token = registration using the HID Approve application integrating HID Approve SDK.

pki.token (do not modify)

OPMODE

(API: opMode)

  • fips_strict – mobile operates in FIPS mode strictly as recommended by the NIST guidelines
  • fips_devbinding – mobile operates using FIPS-approved algorithms and continues to use Secure Element in device for binding (when it exists, even if the FIPS-certified status is unknown)
  • default – mobile operates using best cryptographic practices recommended by HID Global

default

RESYNCH

Defines the credential that will be selected when the device resynchronization function is invoked.

Note: Not used with the HID Approve application integration

CT_TDSOE (do not modify)

AUTHMETHOD

Provisioning method to authenticate the device at the start of provisioning.

It uses a password (computed by the device) on client-side, which must match the password generated on the server (based on a pre-shared secret).

Note: Only the GEN mode is used with the HID Approve application.

GEN|PROMPTPASS|SENDPASS (do not modify)

KDFLEN

(API: kdfLen)

Defines the length used to compute pss (pre-shared secret).

10 (do not modify)

KDKCHARSET

(API: kdfCharset)

Defines the char set used to compute pss (pre-shared secret).

Possible values are:

  • ALPHA – Only uppercase or numeric characters
  • ASCII – the ASCII "94" char set (ASCII printable characters from 0 to 126)

ALPHA (do not modify)

PUSH_NOTIF

(API: pushNotif)

Indicates if push-based notifications should be sent to the mobile device (in the context of push-based action or logon operation validation).

Possible values are:

  • Y – push notifications are sent
  • N – push notifications will not be pushed to the mobile device

Setting PUSH_NOTIF to N allows using the push-based solution without configuring delivery gateways. Instead, “getPending requests” on the mobile device allows retrieving the operations to be validated.

Y

forceInstallation

(API only)

Indicates if the PushID of the mobile device should be registered in Microsoft Azure when sending an HID Approve notification (for example, to create installations in a new hub)

Possible values are:

  • false - the installation will only be created during registration and update with a new PushID

  • true - the installation will also be created before sending the notification

false

Credential Type Common Parameters

In the ActivID Management Console Configuration tab – under Policies, Authentication, then Credential Types.

  • For Mobile Logon (push key: CT_PASAV4), Mobile Action (signkey: CT_TDSV4), and Mobile Transport Key (sessionkey: CT_SMKV4) credentials:

Parameter Description Default Value

Signature Algorithm

Crypto algorithm for approval message signature by the HID Approve application.

SHA256WithRSA (do not modify)

Algorithms restriction (comma delimited, blank means all)

Type of crypto algorithm supported for signature.

RSA (do not modify)

OTP length

(API: otpLen)

One-Time Password (random) that is a part of the encrypted approval message sent to the device.

Allows ActivID Appliance to verify the device’s identity.

8 (do not modify)

Encryption Algorithm

Algorithm used for encryption.

A256CBC-HS512 (do not modify)

Default Approval Status

(API: approvalStatus)

The approval status to be sent to the device.

Any string items are separated by |.

Used as default if the Bank Application does not specify a value when the transaction is created (calling API indirectDeliverChallenge).

Important: DO NOT CHANGE THIS VALUE for deployments with the HID Approve application.

accept|deny|report (do not modify)

Key parameters

See Credential Type Adapter Key Parameters.

Key validity period (days)

(API: keyValidityPeriod)

The number of days for which the credential is valid.

365

Keys protection policy

(API: keysProtectionPolicy)

See Key Protection Policy Parameters.

  • For Mobile OATH (CT_TDSOE and CT_TDSOT) credentials:

Parameter Description Default Value

OCRASuite with counter

Only used for OATH OCRA

N/A

OCRASuite with timestamp

Only used for OATH OCRA

N/A

OTP Key parameters

See OTP Key Parameters (Secure Code).

Key validity period (days)

(API: keyValidityPeriod)

The number of days for which the credential is valid.

365

Keys protection policy

(API: keysProtectionPolicy)

See Key Protection Policy Parameters.

  • For Mobile OATH OCRA for Challenge/Response Mode (CT_TDSOAECR and CT_TDSOATCR) credentials:

Parameter Description Default Value

OCRASuite with counter

Only used for OATH OCRA Event mode authentication.

Note: Must be identical to SERVEROCRASUITE in OTP key parameters when in Event Mode.

OCRA-1:HOTP-SHA1-8:QN08

OCRASuite with timestamp

Only used for OATH OCRA Time mode authentication.

Note: Must be identical to SERVEROCRASUITE in OTP key parameters when in Time Mode.

OCRA-1:HOTP-SHA1-8:QN08-T30S

OTP Key parameters

See OTP Key Parameters (Secure Code).

Key validity period (days)

(API: keyValidityPeriod)

The number of days for which the credential is valid.

365

Keys protection policy

(API: keysProtectionPolicy)

See Key Protection Policy Parameters.

  • For Mobile OATH OCRA for Signature Mode (CT_TDSOAESIGN and CT_TDSOATSIGN) credentials:

Parameter Description Default Value

OCRASuite with counter

Only used for OATH OCRA Event mode challenge response authentication.

Note: Must be identical to SERVEROCRASUITE in OTP key parameters when in  Event Mode

OCRA-1:HOTP-SHA1-8:C-QA48

OCRASuite with timestamp

Only used for OATH OCRA Time mode challenge response authentication.

Note: Must be identical to SERVEROCRASUITE in OTP key parameters when in Time Mode

OCRA-1:HOTP-SHA1-8:QA48-T30S

OTP Key parameters

See OTP Key Parameters (Secure Code).

Key validity period (days)

(API: keyValidityPeriod)

The number of days for which the credential is valid.

365

Keys protection policy

(API: keysProtectionPolicy)

See Key Protection Policy Parameters.

Credential Type Adapter Key Parameters

OTP Key Parameters (Secure Code)

In the ActivID Management Console Configuration tab – under Policies, Authentication, then Credential Types, OTP key parameters.

Parameter Description Default Value

LABEL

(API: keyLabel)

Name for this key on HID Approve application.

For OTP:

  • OATH_event for Event mode
  • OATH_time for Time mode

For Challenge/Response:

  • OATH_OCRA_event_CR for Event mode
  • OATH_OCRA_time_CR for Time mode

For Signature:

  • OATH_OCRA_event_SIGN for Event mode
  • OATH_OCRA_time_SIGN for Time mode

SUPPORTEDALGS

(API: algo)

Define the key usage attached to this key on the HID Approve application.

For OTP:

  • hotp for Event mode
  • totp for Time mode

For Challenge/Response and Signature:

  • ocra

KEYUSAGE

(API: keyUsage)

Define the key usage attached to this key on HID Approve application.

otp (do not modify)

TYPE

(API: type)

Key Algorithm to be associated to the derived key. Default is 'OCT' which is used for symmetric keys.

OCT (do not modify)

RESYNCWIN

(API: validityWindow)

Resynchronization windows.

20 (do not modify)

OTPLEN

OTP length to be generated.

For OTP – 6

Note: This value is not used for Challenge/Response or Signature (OCRA).

ADDCHECKSUM

OATH Check sum flag parameter.

0 (do not modify)

OFFSET

OATH offset parameter.

16 (do not modify)

TIMESTEP

(API: timestep)

OATH time step parameter in seconds.

30 (do not modify)

STARTTIME

OATH start time parameter

0 (do not modify)

CLIENTOCRASUITE

OCRA algo client suite.

Note: Identical to the SERVEROCRASUITE for OCRA.

SERVEROCRASUITE

(API: ocraSuite)

OCRA algo server suite.

* used during the challenge-response exchanges between the server and the HID Approve application.

For Challenge/Response:

  • OCRA-1:HOTP-SHA1-8:C-QN08 for Event mode
  • OCRA-1:HOTP-SHA1-8:C-QN08-T30S for Time mode

For Signature:

  • OCRA-1:HOTP-SHA1-8:C-QA48 for Event mode
  • OCRA-1:HOTP-SHA1-8:C-QA48-T30S for Time mode

* These are the suite parameters that can be modified:

Parameter Description Default value

SHA1-y

y = OTP length to be generated

8

QA0x

x= Challenge length

Note: This value should match the value set in Device Type Capabilities tab.

8

Push Key Parameters (Logon Validation)

In the ActivID Management Console Configuration tab – under Policies, Authentication, then Credential Types, CT_PASAV4.

Parameter Description Default Value

LABEL

(API: keyLabel)

Name for this key on the HID Approve application.

pushkey

KEYUSAGE

(API: keyUsage)

Define the key usage attached to this key on the HID Approve application.

authentication

TYPE

(API: type)

Type of this key.

RSA

ALGO

(API: algo)

Crypto algorithm for signature.

RSA2048

SUITE

(API: ocra)

Crypto suite algorithm for signature.

PKIv1

POPALGOID

Crypto algo used on proof of possession of the private key.

1.2.840.113549.1.1.10

Sign Key Parameters (Action Validation)

In the ActivID Management Console Configuration tab – under Policies, Authentication, then Credential Types, CT_TDSV4.

Parameter Description Default Value

LABEL

(API: keyLabel)

Name for this key on HID Approve application.

signkey

KEYUSAGE

(API: keyUsage)

Defines the key usage attached to this key on the HID Approve application.

signature

TYPE

(API: type)

Type of this key.

RSA

ALGO

(API: algo)

Crypto algorithm for signature.

RSA2048

SUITE

(API: ocra)

Crypto suite algorithm for signature.

PKIv1

POPALGOID

Crypto algo used on proof of possession of the private key.

1.2.840.113549.1.1.10

Session Key Parameters (Mobile Service Communications)

In the ActivID Management Console Configuration tab – under Policies, Authentication, then Credential Types, CT_SMKV4.

Parameter Description Default Value

LABEL

(API: keyLabel)

Name for this key on the HID Approve application.

Sessionkey

KEYUSAGE

(API: keyUsage)

Defines the key usage attached to this key on the HID Approve application.

transactionprotection

ECCCURVE

ECC curve used during establishment of the session transport key.

P-256

ENCMETHOD

Crypto algorithm used to communicate securely with the device using the transport session generated during registration.

A256CBC-HS512

retry

(Optional parameter) Defines the number of times that HID Approve mobile will try to retrieve the operation validation or logon information from ActivID Appliance authentication server.

In HA mode, increase this value in case of network latency to allow mobile HID Approve to wait for operation data to be replicated between HA nodes and avoiding failures when retrieving operation data.

2

delay

(Optional parameter) Defines the delay (in seconds) that HID Approve mobile will wait between retries to retrieve the operation validation or logon information.

3

Key Protection Policy Parameters

The following table lists details about key protection policy parameters.

The policy string is a semicolon separated list of PARAM=VALUE pairs as defined in the following table.

Parameter Description Possible Values

TYPE

(API: type)

Protection type

Available for Device Type (and Credential Type also if using HID Approve SDK):

  • device – protected by mobile device protection, (that is, no extra protection implementation).
  • password – password protection.
  • devicelockorpassword – protected by mobile screenlock security method if it exists at time of registration, else protected by a password.
  • biometricorpassword – protected by biometric credential (fingerprint/face) if it is enabled/available, else protected by a password.

Note: When the Protection type is password, devicelockorpassword or biometricorpassword, the list of parameters must also be defined.

For the other types, these parameters are not required.

Available for Credential Type:

  • container – ensures that the credential will use the protection policy defined in the Device Type Container keys protection policy.
Important: To ensure a user-friendly integration, HID Approve application only supports this default value.

Lock policy (API: lockPolicy)

LOCKTYPE

(API: type)

Password lock policy

  • Delay – an exponential delay is inserted between each failed authentication attempt. This means the user must wait a short period before they can try again.

    This waiting time increases for each failed attempt until number of attempts reaches the COUNTER parameter value.

  • Nolock – password never locks.
  • Lock – password locks when number of attempts reaches COUNTER parameter value.
  • SILENT – password validation is delegated to server-side controls and eventually blocking access on many consecutive failures by augmenting the failed authentication counter. To use this LockType, you need to create an additional Mobile Operation Protection Key Credential Type.

    Note: Password expiration (HISTMAXAGE) and password caching (CACHE_ENABLED) are automatically disabled when the SILENT LockType is configured for use.

DELAY

(API: initialDelay)

When LOCKTYPE is set to Delay, defines the number of times the waiting time is multiplied after an incorrect authentication attempt

The DELAY parameter corresponds to the initial delay in seconds.

The resulting wait is calculated by doubling the initial delay for each failed attempt - wait = DELAY x 2^(attempts-1)

By default, after the fourth failed attempt, the delay will be 16 seconds (where 2 x 2^3).

If you increase the DELAY value to 4, this delay will be 32 seconds (where 4 x 2^3).

Numeric value – default is 2 times

COUNTER

(API: maxCounterValue)

Defines the maximum number of incorrect authentication attempts allowed before the credential locks

Numeric value – default is 6 attempts

The counter is reset to 0 on the next successful authentication

Password policy (API: passwordPolicy)

MINLEN

(API: minLength)

Minimum password length

Numeric value – default is :

  • 6 for existing domains
  • 8 for new domains

MAXLEN

(API: maxLength)

Maximum password length

Numeric value – default is :

  • 8 for existing domains
  • 64 for new domains

UP

(API: minUpperCase)

Minimum number of upper case characters

Numeric value – default is :

  • 1 for existing domains
  • 0 for new domains

LOW

(API: minLowerCase)

Minimum number of lower case characters

Numeric value – default is 0

NUM

(API: minNumeric)

Minimum number of numeric characters

Numeric value – default is 0

ALPHA

(API: minAlpha)

Minimum number of alpha characters

Numeric value – default is :

  • 1 for existing domains
  • 0 for new domains

NALPHA

(API: minNonAlpha)

Minimum number of special characters

Numeric value – default is :

  • 1 for existing domains
  • 0 for new domains

MUP

(API: maxUpperCase)

Maximum number of upper case characters

Numeric value – default is :

  • 8 for existing domains
  • 64 for new domains

MLOW

(API: maxLowerCase)

Maximum number of lower case characters

Numeric value – default is :

  • 8 for existing domains
  • 64 for new domains

MNUM

(API: maxNumeric)

Maximum number of numeric characters

Numeric value – default is :

  • 8 for existing domains
  • 64 for new domains

MALPHA

(API: maxAlpha)

Maximum number of alpha characters

Numeric value – default is :

  • 8 for existing domains
  • 64 for new domains

MNALPHA

(API: maxNonAlpha)

Maximum number of special characters

Numeric value – default is :

  • 8 for existing domains
  • 64 for new domains

History policy (API: historyPolicy)

HISTMAX

(API: maxHistory)

History Maximum Password

This security setting determines the number of unique new passwords that have to be associated with the key before an old password can be reused.

0 authorizes users to reuse current password when password is changed.

Default is 1.

HISTMINAGE

(API: minAge)

History Minimum age

This security setting determines the period of time (in days) that a password must be used before the user can change it. It must be less than the maximum password age.

0 allows changes immediately.

Default is 1 day.

HISTMAXAGE

(API: maxAge)

History Maximum age

This determines how long users can keep a password before they have to change it.

0 means the password never expires.

Default is:

  • 180 days for existing domains
  • 0 days for new domains
Caching policy (API: cachingPolicy)

CACHE_ENABLED

(API: enabled)

Password caching mode

When password caching is enabled, password is prompted before displaying the push transaction content and it is cached during a set time to allow the user to approve/decline the transaction without re-entering the password

  • False – 0
  • True – 1 (default value)

CACHE_TIMEOUT

(API: timeout)

Duration in seconds during which the password is kept in cache

Numeric value – default is 30

Maximum allowed is 300 seconds

Note: About Password Policies

When defining the rules of the password policy, make sure that there are no logical conflicts. For example, do not specify that the minimum number of numeric characters is 8, in combination a maximum password length of 6 characters.

It is possible to define an exclusive numeric policy which is more user-friendly in mobile authentication deployments. For example:

UP=0;LOW=0;NUM=6;ALPHA=0;NALPHA=0;MUP=0;MLOW=0;MNUM=8;MALPHA=0;MNALPHA=0;MINLEN=6;MAXLEN=8

It is also visually effective when displayed as the HID Approve application tooltip during the password setup process.

In addition, it is recommended that you test the password policy on the HID Approve application before deploying it to your user population.

Request Expiration Parameters

Below are the parameters to configure the validity/timeout periods for the provisioning and transaction requests.

Provisioning Request

Edit the Validity period of password setting of the CT_TDSOOB Credential Type (default value is 1800 seconds).

This means that, by default, a service can be registered on HID Approve app using the QR code scan or the manual invitation code up to 30 minutes (1800 seconds) after the Service has been requested.

This duration can be extended, but it is recommended to keep it as short as possible.

At the end of the timeout, the Service Registration will fail.

Note: By default, a registration request (QR code) cannot be reused so if registration fails, a new registration request (QR code) must be generated.

However, this default policy can be updated by defining the number of QR code retries in the Default expiry threshold parameter of the Mobile Registration Authentication Policy (AT_TDSOOB):

This value sets the number of times that a user can try to scan a QR code (for example, if device registration fails due to network connection failure).

Transaction Request

You can edit the AT_TDS (Action Validation) or the AT_PASA (Logon Validation) Authentication Policies as follows:

  • Challenge timeout period(s) (challengeTimeoutPeriod, default value is 3600 seconds)

    This means that, by default, a transaction (Logon or Action) can be retrieved, then approved or denied on HID Approve app up to 1 hour after the transaction operation has been initiated.

    This duration can be extended, but it is recommended to keep it as short as possible.

    After timeout, the transaction will no longer be retrieved by the app, or if it has already been retrieved, the approval/decline operation will fail.