Configuring the Identity Portal Workflow

accessCriteriaId

The unique criteria identifier

Mandatory

authenticators

Define how access should be filtered based on the user's existing authenticators:

• firstFactorsFiltering - access to the authentication flow is allowed only if the user has an authenticators matching one of the first authenticator factors defined in the template.

  Possible values are true or false.

• secondFactorsFiltering - access to the authentication flow is allowed only if the user has an authenticators matching one of the second authenticator factors defined in the template.

  Possible values are true or false.

• acrFiltering - allows filtering the authentication flow templates based on the ACR claim (if part of the authentication request) and the template's authentication policies.

  Possible values are true or false.

Mandatory

actionId

The unique identifier of the action

Mandatory

name

The name of the action (for internal reference only)

Optional

description

The description of the action (for internal reference only)

Optional

accessCriteriaId

The unique identifier of the criteria to apply (action is available only if the user matches the criteria)

Mandatory

type

The type of action that can be performed

Mandatory

CHANGE_PWD - the user can click the 'Change your Password' link if the action.change_password action is defined for the factor

The user is redirected to the 'Change Password' flow.

FORGOT_PWD - the user can click the 'Forgot your Password?' link if the action.request_reset_password action is defined for the factor

The user is redirected to the 'Reset Password' flow.

The user can select the temporary password delivery method if resetPasswordMethods is present/defined.

For FORGOT_PWD only, the validity (in seconds) of the temporary password

The default value is 900 seconds.

retry

The maximum number of failed action attempts allowed with this factor before the user is redirected back to the authorization request initiator (service provider)

The try count is kept per action. Selecting another authenticator does not reset the retry count.

Optional

resetPasswordMethods

Define the temporary password delivery methods (email and/or SMS) available to the user when they have forgotten their password

If not defined, the server will select the delivery adapter based on the user information and authentication policy.

You can select either email, SMS or both, as well as specify the message content:

• email:

  • template - define the content of the email message:

    "MESSAGE=Use the following temporary password to complete the authentication process {$secret}",

  • templateHtml - define if the email format is HTML(possible values are true or false)

• sms:

  • template - define the content of the SMS message:

    "MESSAGE=Use the following temporary password to complete the authentication process {$secret}"

If you want to localize the message, update the content with the required language codes and separate each localized message with a carriage return character (\r). For example:

"MESSAGE_en=Use the following temporary password to complete the authentication process {$secret}\r MESSAGE_fr=Utilisez ce mot de passe temporaire pour continuer {$secret}"

Optional

factorId

The unique identifier of the authentication factor

Mandatory

name

The name of the factor (for internal reference only)

Optional

description

The description of the factor (for internal reference only)

Optional

accessCriteriaId

The unique identifier of the criteria to apply (authentication factor available only if user match criteria)

Mandatory

code

The code of the authentication policy to use for this specific factor

Mandatory

type

The type of authenticator for this specific factor

Mandatory

LOGIN - the user enters their static password

For this type, you can also add the optional actions parameter to define the links available to the user for the authentication factor.

Possible values are:

• action.change_password - a link is displayed allowing the user to change their password

• action.request_reset_password - a link is displayed allowing the user to reset their password if they have forgotten it

OTP - the user enters an OTP generated using a registered device

OOB - the server triggers the delivery of an OTP

The user can select the OTP delivery method if oobMethods is present/defined.

CODE - the user enters their activation code to trigger the delivery of an OTP

The user can select the OTP delivery method if oobMethods is present/defined.

PKI - the user authenticates with their digital certificate

FIDO - the user authenticates with a FIDO passkey

For this type, you can also define:

• rpId - (optional) defines the customer back-end hostname for integrations using the API

  If users will authenticate to different applications in multiple sub-domains with their FIDO passkey, specify the root domain. The value must match the hostname for the FIDO enrollment factor.

• userVerification - (mandatory) defines if the user is required to verify their presence by performing an action on the passkey (such as providing the PIN, biometric credential or touching the device-bound passkey) to access the authenticator. Possible values are:

  • required

  • preferred

  • discouraged

• discoverCredentialsInDevice - (optional) defines the credentials made available to the user. Possible values are:

  • true - the user will only be able to choose from a list of discoverable keys

    In the enrollment flow, residentKey must be set to required.

  • false - the workflow returns the list of all the credentials available for the user (default)

• enrollActions - (optional) a comma-separated list of the enrollment action identifiers for which the workflow should be triggered if the user does not have a corresponding authenticator

CARD - the user authenticates with their contactless smart card

For this type, you can also define:

• enrollActions - (optional) a comma-separated list of the enrollment action identifiers for which the workflow should be triggered if the user does not have a corresponding authenticator

  • If defined as a first-factor authentication, the enrollment must be protected (see Enable Enrollment Protection)

  • If defined as second-factor authentication, enrollment protection is optional

PUSH - the user authenticates by approving a push notification received on their registered device

For this type, you can also define:

• pollTimeout - specify the timeout (in seconds) to wait for the push result (to exit the loop of polling the back end)

• allowUserDeviceSelection - specify if the user is allowed to select the device on which to receive the push notification if they have more than one registered device (possible values are true or false)

  If set to true, the list of devices is displayed for this factor (with the device's friendly name if defined)

• tds - specify the message displayed on the HID Approve application to prompt the user to approve or deny the authentication (by default, "Logon to portal")

• device - server-populated list of available devices for push authentication for the user

QRCODE - the user authenticates by scanning a QR code without needing to provide their User ID (userID-less authentication)

If they do not want (or are unable) to scan the QR code and the:

• login_hint is present in the authentication request - the IdP retrieves a workflow adapted for the user so they can select an alternative authentication method from their list of enrolled authenticators without needing to provide their User ID

• login_hint is NOT present - the IdP displays the default workflow and the user will be required to provide their User ID to generate the list of available authenticators

For this type, you can also define:

• forceDisplay - define (true or false) if the QR code should be displayed directly as the proposed authentication method

• pollTimeout - specify the timeout (by default, 30 seconds) to wait for the user to scan the QR code before it expires

• cal - specify a subset of the credential type's default approval status sent to the device for a userID-less QR code operation (by default, "accept|deny")

  For mobile applications built using the HID Approve SDK, this value must match that defined for the cal parameter of the bcauthorize endpoint.

• tds - specify the message displayed on the HID Approve application to prompt the user to approve or deny the scanned QR code authentication (by default, "Logon to portal")

LDAP - the LDAP federated user (Microsoft Azure AD or AD FS) authenticates with their directory-based password

For this type, you can also define:

• automaticOOBEnrollment - specify the factorId of the OOB factor/authenticator to be used for auto-enrollment (for example, factor.otp_oob_adt)

  This OOB factor should be defined as a secondFactor with the corresponding LDAP factor defined in its upon parameter.

  If automaticOOBEnrollment is not defined, OOB auto-enrollment is disabled.

acr

The default HID Authentication Service authentication policies include an ACR value that defines the level of assurance (LoA) provided by the identity authentication process.

You can use this parameter to override the acr value defined in the authentication policy associated with the factor by setting a string value that corresponds to your organization’s requirements.

For example, if you define the same authentication method as both a first and second authentication factor, you can set a higher level of assurance when it is used as a second authentication factor.

For Microsoft Entra ID integrations, the value should be possessionorinherence.

Mandatory for Microsoft Entra ID

Otherwise optional

Supported values are:

• fido - FIDO2

• hwk - hardware-secured key

• otp - one-time password

• pop - proof of possession

• sc - smart card

• sms - text to registered number

• swk - software-secured key

Mandatory for Microsoft Entra ID

Otherwise optional

stepUp

Defines if the user needs to provide a second authentication factor as part of the step-up workflow:

• notRequired - if a second factor is not defined, then authentication with this first factor is sufficient

• automatic - (default if parameter is present but not defined) if the user has a second and compatible authentication method available, then step up is enforced. Otherwise, authentication with this first factor is sufficient

• required - (default if parameter not present) a second factor is required. Otherwise, authentication will fail

Optional

retry

The maximum number of failed authentication attempts allowed with this factor before the user is redirected back to the authorization request initiator (service provider)

The default value is 1 if the parameter is not present/defined.

Mandatory

oobMethods

Defines the OTP delivery methods (email and/or SMS) available to the user for OOB authentication

If not defined, the server will select the delivery adapter based on the user information and authentication policy.

You can select either email, SMS or both as well as define the message content:

• email:

  • template - define the content of the email message:

    "MESSAGE=Use the following OTP to complete the authentication process {$secret}",

  • templateHtml - define if the email format is HTML(possible values are true or false)

• sms:

  • template - define the content of the SMS message:

    "MESSAGE=Use the following OTP to complete the authentication process {$secret}"

If you want to localize the message, update the content with the required language codes and separate each localized message with a carriage return character (\r). For example:

"MESSAGE_en=Use the following OTP to complete the authentication process {$secret}\r MESSAGE_fr=Utilisez ce code pour continuer {$secret}"

Optional

expirationWarningThreshold

The threshold (in seconds) after which a warning that the authenticator will expire is displayed

For further information, see Manage the Authenticators in the Authentication Flow.

Optional

upon

A comma-separated list of the first factor authenticator identifiers for which the second factor authentication should be triggered

For example, when a user authenticates with their static password as the first factor and you want to enforce push authentication as the second factor, specify the factorId of the static password authenticator that should trigger the push authentication step.

Optional

enrollId

The unique identifier of the enrollment action

Mandatory

name

The name of the action (for internal reference only)

Optional

description

The description of the action (for internal reference only)

Optional

accessCriteriaId

The unique identifier of the criteria to apply (factor is available only if the user matches the criteria)

Mandatory

code

Code of the authentication policy to use for this specific enrollment

Mandatory

type

Type of authenticator for this specific enrollment action:

• FIDO (U2F or UAF (FIDO2))

• CARD

Mandatory

rpId

For FIDO factors only, defines the customer back-end hostname for integrations using the API

If users will authenticate to different applications in multiple sub-domains with their FIDO passkey, specify the root domain.

For example, if the FIDO enrollment application is in enroll.companydomain.com and the FIDO authentication application is in auth.companydomain.com, the root domain value is companydomain.com

The FIDO authentication factor also supports multi-domain configuration and the root domain value must match the value defined for the FIDO enrollment action.

Optional

userVerification

For FIDO factors only, defines if the user is required to verify their presence by performing an action on the passkey (such as providing the PIN, biometric credential or touching the device-bound passkey) to access the authenticator

Possible values are:

• required

• preferred

• discouraged

Mandatory

residentKey

For FIDO factors only, defines if a discoverable resident key should created on the FIDO passkey during enrollment

Possible values are:

• discouraged - a non-resident key is preferred (that is, the user information and credential ID is stored on the server) but HID Authentication Service will accept a resident key

• preferred - the resident key is preferred (that is, the user information and credential ID is stored on the FIDO passkey) but HID Authentication Service will accept a non-resident key

• required - the resident key is required (that is, the user information and credential ID is stored on the FIDO passkey)

  If the request is denied by the FIDO passkey, enrollment will fail.

The default value is preferred.

Optional

For FIDO factors only, defines the FIDO platform that will be proposed during enrollment

Possible values are:

• platform - only the passkey platform will be proposed (such as Microsoft Windows Hello, Google Android or Apple iOS platform keys)

  Roaming keys and or external security keys will not be proposed

• cross-platform - all platforms will be proposed (default)

For FIDO factors only, a JSON array of FIDO AAGUID (Authenticator Attestation Global Unique Identifier) to specify the passkeys that users are allowed to enroll

• If present, only the specified passkeys can be enrolled

• If not present, no restriction (all passkeys can be enrolled)

allowedCards

For CARD factors only, a a comma-separated list of the IDs of the allowed card applications

If none are specified, all existing card applications are allowed

The maximum number of failed attempts to communicate with the device with this factor before the user is redirected back to the authorization request initiator (service provider)

The default value is 1.

deviceType

For FIDO factors only, code of the device type to use for this specific enrollment action

Mandatory

credentialType

For FIDO factors only, code of the credential type to use for this specific enrollment action

Mandatory

deviceBinding

Defines if the user must have a "pending" device of the specified device type to be able to enroll their credential

Possible values are:

• required

• notRequired

• If absent or undefined, the value is considered to be notRequired

If you set this to required, you must:

• For FIDO, create and assign a FIDO device authenticator for the user before they can enroll their passkey

• For CARD, create and assign a card authenticator for the user before they can enroll their smart card

Optional

attestationVerification

For FIDO factors only, defines if the user's FIDO passkey is required to provide an attestation statement for verification at enrollment

Possible values are:

• none - the attestation statement is not required

• direct - the attestation statement should generated by the passkey

For further information, see Enable Attestation.

Optional

enrollValidation

Defines the if enrollment should be validated by a successful authentication using the newly enrolled authenticator

Possible values are true or false.

Optional

protectionFactor

Defines the protection factor applied for the enrollment action

Optional

localizationKeyRedefinition

List of redefined localization label keys

Allows to redefine (override) the default label keys present in the localization configuration.

The left part is the default key. The right part is the redefined key.

For example:

"localizationKeyRedefinition": {
	"enroll.fido.uaf.label": "enroll.fido.cust_uaf.label",
	"enroll.fido.uaf.placeholder": "enroll.fido.cust_uaf.placeholder"
}

Optional

protectionFactorId

The unique identifier of the protection factor

Mandatory

name

The name of the protection factor (for internal reference only)

Optional

description

The description of the protection factor (for internal reference only)

Optional

code

The code of the authentication policy to use for this protection factor

Mandatory

type

The type of authenticator for this protection factor:

LOGIN - the user enters their static password

PKI - the user authenticates using their digital certificate

FIDO - the user authenticates with a FIDO passkey

PUSH - the user authenticates by approving a push notification received on their registered device

Mandatory

retry

The maximum number of failed authentication attempts allowed with this factor before the user is redirected back to the authorization request initiator (service provider).

The default value is 1 if the parameter is not present/defined.

Optional

workflow_id

The unique identifier of the authentication configuration definition to be used for the client

The content of configuration defines the flow and authentication factors. See Create the Authentication Workflow

If absent or contains an incorrect ID, the OpenID client registration returns error.

Mandatory

theme_id

The unique identifier for theme definition

The content of the theme defines the customization for application interface such as titles and labels. See Customizing the Identity Portal

If empty, the default theme is used.

Optional

hid_federation_audiences

To allow other applications to use the user's authenticated session for this client application (for example, client_INIT), add the OpenID client ID of the allowed application(s), where the format of the value should be a regular expression.

For example, in the following use cases:

• To allow access for one or more applications, use the format client_ID1|client_ID2

• To allow access for all clients with a specific ID (for example, starting with 'HID'), set the value to ^HID.*

hid_sso_session_validity

In the configuration of the client application(s) that will use the SSO session, define the maximum age limit of the existing SSO session (in seconds and greater than 0).

If a user tries to log on after this limit is reached, and even if the initial authenticated session is still valid, they will be required to re-authenticate.

The default value is 0 and if the parameter is not present (or set to 0), SSO support is disabled.