Customize the User Authentication Process

You can customize the ActivID Authentication Portal logon process and display so that users are redirected to authentication pages that display only specific items or actions.

To do so, you can create customized:

  • Authentication GUI templates – defines the way an authentication policy is represented in the graphical user interface (GUI) of a logon. It provides the list of input fields presented to the user when the related authentication policy has to be enforced.

  • Authentication process templates – assigns a specific representation of the ActivID Authentication Portal page to a specific channel. You can customize the process so that users are redirected to the appropriate authentication page that displays only the possible actions that the user can perform (such as token activation).

The templates are managed via the ActivID Authentication Portal configuration page in the ActivID Console.

ActivID Appliance includes a set of default authentication GUI templates but not default authentication process templates.

Note: You can only delete customized templates, not the default templates. It is recommended that you contact HID Global Professional Services for guidance.

The authentication policies supported by the ActivID Authentication Portal are associated with GUI templates. The following table lists the GUI templates associated with the authentication policy.

Authentication Policy GUI Templates

Static Password

(Employee Static Password)

  • Username/Password

  • Seeded Username Password

LDAP Password

(LDAP Fallback/Passthrough)

  • LDAP Username Password

Security Questions and Answers

(Employee Emergency Q&A)

  • Question/Answers

  • Seeded Question/Answers

OOB Authentication (Out of Band)

(Employee OOB Authentication)

  • One-Time-Password (synchronous)

  • OOB One-Time Password

  • Mail OTP

    To be used for second step tiered-authentication. It does not require an Activation code, the OTP is sent by mail.

  • SMS OTP

    To be used for second step tiered-authentication. It does not required an Activation code, the OTP is sent by SMS.

One-Time-Password

(Employee One Time Password)

  • One-Time-Password (synchronous)

  • Challenge Response (asynchronous)

PKI Authentication

(Citizen PKI Authentication)

  • Public Key Infrastructure

  • Auto Public Key Infrastructure

EMV Authentication

  • Public Key Infrastructure

  • Transaction signing

Mobile push-based Logon Validation

  • TDS Push

Legacy template for Push-Based Authentication support.

It performs user Static Password authentication, then push-based authentication.

  • Push-Based Authentication

To be used for second step tiered-authentication (for example, with Static Password as the first step authentication).

FIDO U2F authentication

FIDO device authentication

To be used for the second step of a tiered-authentication deployment (for example, with Static Password as the first step authentication).

Customize an Authentication GUI Template

The authentication GUI templates available when accessing the ActivID Authentication Portal via a Service Provider is determined by the list of:

  • Authentication policies enabled for the channel related to the Service Provider (configured for the channel).

  • Authentication GUI templates per authentication policy defined by the authentication policies mappings configuration in the ActivID Management Console.

You can define custom authentication GUI template and assign it to a channel/authentication policy pair. This template will be then displayed when accessing the ActivID Authentication Portal via the given channel.

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

  2. Click Edit Settings for the ActivID Authentication Portal in the Applications list.

  3. Select the Authentication GUI Templates tab.

    4. The Authentication GUI Templates section lists all the available templates and their type:

    • Default – templates delivered out of the box and that are read-only. They cannot be altered or deleted.
    • Custom – templates that have been uploaded.

    The following table lists the different types of authentication policies with the expected prefix for the related authentication GUI templates:

    Type of Authentication PolicyAuthentication GUI Template Prefix
    LoginUP
    PKIPKI
    OOB OnlyOOB_ONLY
    OTP OnlyOTP_ONLY
    Both OTP and OOBOTP
    Memorable DataSQ
    LDAP PassthroughLDAP
    Mobile push-based validationTDS_PUSH

    For example, a new Login template should be named UP_MYTEMPLATE.

  4. Click on the name of the required template to download it.

  5. Open the downloaded file and edit the required authentication GUI template elements. These include:

    • Title
    • Explanation message
    • User name field and label
    • Password or other authentication material field and label

ActivID Appliance Authentication GUI Template Elements

Element Description Mandatory Number of occurrences Attributes

<configuration>

The root element.

Yes

1

None

<configuration>
<name>

The GUI template name, used to uniquely identify the template.

Yes

1

None

<configuration> <description>

An internal description of the template.

No

[0, 1]

None

<configuration> <entries>

Contains the ordered list of the GUI Entries (user prompts).

Yes

1

None

<configuration>
<entries> <entry>

Describes a data involved in the authentication process (for example, the “user name” and the “static password”).

Yes

[2, 10]
  • readOnly – Indicates if this entry is modifiable.
  • sensitive – Indicates if this entry should not be echoed.
  • key – Entry type (reserved keywords): username password newpassword confirmnewpassword challenge sign0 sign0 sign1 sign2 sign3 sign4 minanswers seedsqinfo seedupinfo
  • dynamic – Reserved for future use.
  • label – (Optional) localization key of the label value in ac-4tress-portal_en.properties.
    If the label is not specified, the label value is the one defined by the ai.samlidp.template.<key> property in the ac-4tress-portal_en.properties file.

<configuration> <entry> <value>

Reserved for future use.

No

[0, 1]

None

<configuration> <entry> <entryCriteria>

Reserved for future use.

No

[0, 1]

None

configuration> <id>

Reserved for future use.

Yes

1

None

<configuration> <id> <id>

Reserved for future use.

Yes

1

None

<configuration> <id> <type>

Reserved for future use.

Yes

1

None

<configuration> <syntax>

Description of the restrictions applied to each field of the template (maximum length, data type etc.).

Yes

1

None

  1. Save the file with the existing template name (it will override the existing template with the same name), or save it with a new name (that corresponds to the purpose of the template).

  2. In the Authentication Templates page, upload the new or edited template.

  3. Browse to the required template and click Add.

    4. The uploaded template is automatically checked and the content is validated. If the template is not compatible, it is rejected.

  4. Restart the ActivID Appliance applications.

  1. Declare the new authentication GUI template in the ActivID Management Console:

    1. If it does not already exist, create a ac-4tress-mgtcons_en.properties file in the ManagementConsole/branding/_common_/mc folder (you can make a copy of the default file in the ManagementConsole/branding/default/mc folder).

    1. In this properties file, add the new authentication GUI template name to the (comma-separated) list of available authentication GUI templates by adding it to the list defined in the ai.configuration.policies.saml.ftressidp.authpolicymapping.guilist property. For example:

      Copy 
      ai.configuration.policies.saml.ftressidp.authpolicymapping.guilist=UP_MYTEMPLATE,OTP_ASYNC_start,OTP_SYNC,OTP_SYNC_WT,OTP_SYNC_WT_HIDE,OTP_ASYNC_WT,OTP_ASYNC_WT_HIDE,PKI_auto,PKI,SQ_NOTSEEDED_start,SQ_SEEDED_start,UP_NOTSEEDED,UP_SEEDED_start,OTP_SYNC_OOB,LDAP_UP

      2. The original list is available in the default configuration file (ac-4tress-mgtcons_en.properties in ManagementConsole/branding/default/mc).

    1. In the same properties file, add a label for the new authentication GUI template. This label will be used for the authentication policies mappings. The key for the entry must be in the format:

      2. ai.configuration.policies.saml.ftressidp.authpolicymapping.<TEMPLATE_NAME>

      For example, add the following label for the UP_MYTEMPLATE:

      Copy 
      ai.configuration.policies.saml.ftressidp.authpolicymapping. UP_MYTEMPLATE=My User/Password Template

  2. Restart the ActivID Appliance applications.

  3. Configure the authentication policies mapping with the new authentication GUI template using the ActivID Management Console:

    4. After several minutes, the new authentication GUI template will be available in the ActivID Authentication Portal.

Customize an Authentication Process Template

  • If no authentication process templates are specified for a given service provider, or if the ActivID Authentication Portal is accessed via a multi-domains SAML endpoint, then the default authentication flow applies (that is, all the authentication policies configured for that channel are displayed, and the user selects the appropriate one).

  • When an authentication process template is specified, and there is only one domain or the ActivID Authentication Portal is accessed via a single domain endpoint, there are two options:

    • If the user has requested a service provider URL that is not bound to an action, the welcome page with direct links is displayed and the user is redirected to the appropriate authentication page depending on the selected link.
    • If the user has requested a service provider URL that is bound to an action, the welcome page is not displayed and the user sees only the authentication policies available on both the channel and the authentication process template.

The authentication process templates are common to all domains but an action can be specific to a subset of domains.

Channels of different domains can be differentiated by using different channel codes on the different domains.

Important: For deployments with several domains, the domain name should be specified in the URL of the ActivID portal (Management Console or Self Service Portal) for the template usage to be triggered. For further information about URI domain name configuration, see Specify the Domain in the URI.

You can define custom authentication process templates for a channel. This authentication process template will then be displayed when accessing the ActivID Authentication Portal via the given channel (provided there is no ambiguity on the domain).

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

  2. Click Edit Settings for the ActivID Authentication Portal in the Applications list.

  3. Select the Authentication Process Templates tab.

    4. The Authentication Process Templates section lists all the available templates and on which channel they apply.

    By default, there are no templates available.

  4. Click Download to download the required template.

  5. Open the downloaded file and edit the required authentication process template elements. These include:

    • Welcome message (for example, “Welcome, what do you want to do?”).
    • Name – the name displayed as the link for a given operation (such as “Activate a new token”).
    • Channel code (for example, CH_SSP).
    • Type – if it is a generic template or channel-specific.
    • URL – the URL to the required action within the SP site (for example, in the Self-Service Portal, a direct link to the activation page).
    • Description (optional) – Allows displaying a brief description explaining the purpose of the action.
    • List of SAML authentication class (optional) per domain.

    6. The authentication page that is displayed to the user is the resulting match (intersection) between the lists of:

    • SAML authentication classes configured in the template for that domain.
    • SAML authentication classes as configured for each channel into the ActivID Management Console IdP screen for that domain.

ActivID Appliance Authentication Process Template Elements

Element Description Mandatory Number of occurrences Attributes

<actionspage>

Root element

Yes

1
  • width – the width of the page where the actions are displayed. Depending on the ratio with action box widths, the actions will be displayed on one or multiple columns layout.
  • type – type of the page. Possible values are:
    • sp – Template bound to a Service Provider
    • idp – Reserved for future use.

<actionspage> <name>

Name of the authentication process template.

Yes

1

None

<actionspage> <channel>

A valid channel name (for example, CH_SSP).

Only if the ActionPage type is set to sp

1

None

<actionspage> <description>

Description as displayed by the ActivID Authentication Portal.

No

[0, 1]
  • font-weight – bold or normal.
  • width – width of the solid box around the description text.

<actionspage> <actions>

Contains the ordered sequence of actions.

Yes

1

None

<actionspage> <actions> <action>

Root element on an action.

Yes

[1, 10]
  • id – a unique identifier of the action in the welcome page. This id is used in the context of the localization of the Actions’ texts in the ac-4tress-portal_<locale>.properties files.
  • width – width of the Action box.
  • height – height of the Action box.

<actionspage> <actions> <action> <uri>

The resource URI is used by the service provider to redirect the user after a successful authentication to a specific resource (also known as "SAML relaystate").

For the ActivID Self-Service Portal, this URI should match one of the direct URLs available (for example, /tab/activate-token/activateTokenHome.xhtm).

Yes

1

type – the URI type. The only possible value is “resource”.

<actionspage> <actions> <action> <name>

Name of the action as displayed by the ActivID Authentication Portal.

Yes

1

None

<actionspage> <actions> <action> <background>

Background image representing the action and displayed by the ActivID Authentication Portal.

  • If not specified, the action is displayed in a solid box.
  • If the Action’s box is bigger than the background image, the image is repeated.
  • If the Action’s box is smaller than the background image the image is not displayed nor the solid box.

No

1

None

<actionspage> <actions> <action> <description>

Description of the action as displayed by the ActivID Authentication Portal.

No

1

None

<actionspage> <actions> <action> <auth-description>

Authentication description of the action as displayed by the ActivID Authentication Portal in the login page.

If set, this text will overrides the bottom left text of the login page.

No

1

None

<actionspage> <actions> <action> <authpolicy>

Root element of the section describing the authentication policy managed by the action.

If the <authpolicy> element:

  • Is optional, the default list of authentication class URI considered is the one corresponding to the list of authentications policies available for the channel (specified in the <channel> element).
  • Can contain multiple authentication class URI, the login page will present only authentication class URI available for the channel and domain used.
Note: If the SAML request received by the ActivID Authentication Portal contains a list of authentication class URI, then only the intersection between this list and the one defined in the template will be displayed.

No

[0, 1]

None

<actionspage> <actions> <action> <authpolicy> <authclass>

Authentication class URI as defined in the ActivID Identity Provider (the authentication class URI can be defined in the ActivID Management Console in the ActivID Identity Provider configuration page).

Yes

[1, n]

None

<actionspage> <actions> <action> <alt-uri>

Contains a list of URI requiring the same Login page configuration as the action principal URI.

No

[0, 1]

None

<actionspage> <actions> <action> <domains>

Restricted list of domains (list of domain names comma separated) on which the action is applied.

No

[0, n]

None

  1. Save the file with the existing template name (it will override the existing template with the same name), or save it with a new name (that corresponds to the purpose of the template).

  2. In the Authentication Templates page, upload the new or edited template.

  3. Click Add.

    4. The uploaded template is automatically checked and the content is validated. If the template is not compatible, it is rejected.

  4. Restart the ActivID Appliance applications.

    5. After several minutes, the new authentication process template will be available in the ActivID Authentication Portal.

Copy

Example of an Authentication Process Template

<?xml version="1.0" encoding="UTF-8"?>
<actionspage width="370" type="sp">
    <name>Self Service Portal Custom</name>
    <channel>CH_SSP</channel>
    <description font-weight="bold" width="370" >Welcome. What do you want to do?</description>
    <actions>
        <action id="1" width="350" height="170">
            <uri type="resource">/tab/activate-token/activateTokenHome.xhtml</uri>
            <name>Activate a New Token</name>
            <background>box_activate.jpg</background>
            <description>Activate my device so I can use it to login to my applications. Works with mobile phones, tablets, web browsers, PC and OTP tokens.</description>
            <auth-description>Enter your Domain Username and Password</auth-description>
            <authpolicy>
                <authclass>SSP.EMPOTPActivateToken</authclass>
            </authpolicy>
            <alt-uri>
                <uri type="resource">/tab/activate-token/activateHardwareToken.xhtml</uri>
                <uri type="resource">/tab/activate-token/activateWebSoftToken.xhtml?type=STW</uri>
                <uri type="resource">/tab/activate-token/activatePCSoftToken.xhtml?type=STP</uri>
                <uri type="resource">/tab/activate-token/activateSoftTokenApplication.xhtml?type=STM</uri>
            </alt-uri>                
        </action>
        <action id="2" width="350" height="170">
            <uri type="resource">/tab/my-devices/list/deviceList.xhtml</uri>
            <name>Manage an Existing Token</name>
            <background>box_devices.jpg</background>
            <description>View, update, test or discard any of my devices.</description>
            <auth-description>Enter your Username and OTP with PIN</auth-description>
            <authpolicy>
                <authclass>SSP.EMPOneTimePassword</authclass>
            </authpolicy>
            <alt-uri>
                <uri type="resource">/tab/my-devices/test/testDeviceSelect.xhtml</uri>
                <uri type="resource">/tab/my-devices/list/renameDeviceSelect.xhtml</uri>
            </alt-uri>                
        </action>
        <action id="3" width="350" height="170">
            <uri type="resource">/tab/my-problem/cannot-login/cannotLogin.xhtml</uri>
            <name>Emergency Access</name>
            <background>box_problem.jpg</background>
            <description>Troubleshoot problem login in to applications or report lost, stolen or damaged device.</description>
            <auth-description>Enter your Domain Username and Password</auth-description>
            <authpolicy>
                <authclass>SSP.LDAPFallback</authclass>
            </authpolicy>
            <alt-uri>
                <uri type="resource">/tab/my-problem/lost/deviceLost.xhtml</uri>
                <uri type="resource">/tab/my-problem/myProblemHome.xhtml </uri>
            </alt-uri>            
        </action>        
    </actions>        
</actionspage>

Displays as: