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 ActivID Identity Provider (IDP) customization files for the ActivID Authentication Portal are stored in the <ACTIVID_HOME>/ActivID_AS/applications/resources/ap/4tress-idp-templates folder on the file system.

In a customization package, the folder path is AuthenticationPortal/config/templates.

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

Prerequisites: You have created a reference customization package.

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.

The authentication GUI templates are XML files stored in the AuthenticationPortal/config/templates/gui folder of the customization package.

The AuthenticationPortal/config/templates/gui/default folder contains the default ActivID Authentication Portal authentication GUI templates. They cannot be deleted.

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. Create an XML file with a filename that includes the specific prefix to link it to the appropriate type of authentication policy.

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

    Type of Authentication Policy Authentication GUI Template Prefix
    Login UP
    PKI PKI
    OOB Only OOB_ONLY
    OTP Only OTP_ONLY
    Both OTP and OOB OTP
    Memorable Data SQ
    LDAP Passthrough LDAP
    Mobile push-based validation TDS_PUSH

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

  2. Edit your new template file and add the required authentication GUI template elements as illustrated below:

    Copy 
    <configuration>    
        <name>…</name>
        <description>…</description>
        <entries>
            <entry>
                <label>…</label>
                <value>…</value>
                <entryCriteria>…</entryCriteria>
            </entry>
            …
            <entry>
                <label>…</label>
                <value>…</value>
                <entryCriteria>…</entryCriteria>
            </entry>
        <id>
            <id>…</id>
            <type>…</type>
        </id>
        <syntax>…</syntax>
    </configuration>

ActivID AS 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. Copy the XML file to the AuthenticationPortal/config/templates/gui folder of the customization package.

  2. If you have not previously customized your deployment, manually create the _common_ and/or domain-specific folders using the default folder as a template.

  3. Add the customization labels for the new authentication GUI template in the ActivID Authentication Portal branding configuration.

  4. If it does not already exist, create a ac-4tress-portal_en.properties file in AuthenticationPortal/branding/_common_/ap folder of the customization package (you can make a copy of the default file in the AuthenticationPortal/branding/default/ap folder).

  5. In this properties file, add the labels for the new authentication GUI template – one each for its title, description and the alternative text for an icon.

    6. Each entry must have its key ending with the name of the template. For example, add the following labels for the UP_MYTEMPLATE:

    Copy 
    ai.samlidp.template.title. UP_MYTEMPLATE=My Username Password
    ai.samlidp.template.description. UP_MYTEMPLATE=Login with your password in my template
    ai.samlidp.template.icon. UP_MYTEMPLATE= My Username Password Template

  6. Add the image to use as the new authentication GUI template icon that will be displayed in the authentication method selection screen. This image must meet the following conditions:

    • The filename is the name of the template (for example, UP_MYTEMPLATE).
    • The file extension is .png.
    • It is stored in the AuthenticationPortal/branding/_common_/ap/img folder (for domain-specific folder).

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

  4. Apply the customization package.

In addition, if you want to replicate the new authentication GUI template to other ActivID AS servers in your deployment:

  1. Create a customization package of the authentication GUI template you created above.

  2. Apply the customization package to each server hosting either the ActivID Authentication Portal and/or the ActivID Management Console.

Note: The configuration for authentication policies mapping has to be done only once, as this configuration is stored into the shared database. You do not need to repeat the steps on replicated servers.

Customize an Authentication Process Template

Prerequisites: You have created a reference customization package.

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

Authentication process templates are XML files and are stored in the <ACTIVID_HOME>/ActivID_AS/applications/resources/ap/4tress-idp-templates/process folder.

In a customization package, the folder path is AuthenticationPortal/config/templates/process.

Note: By default, the process folder is not present when creating the customization package so you should create it.

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. Create an XML file for the new authentication process template (for example, to customize the ActivID Self-Service Portal, CH_SSP_CUSTOM.xml).

  2. Edit your new template file and add the required authentication process template elements as illustrated below:

    Copy 
    <actionspage>
        <name>…</name>
        <channel>…</channel>
        <description>…</description>
        <actions>
            <action>
                <uri>…</uri>
                <name>…</name>
                <background>…</background>
                <description>…</description>
                <auth-description>…</auth-description>
                <authpolicy>
                    <authclass>…</authclass>
                <alt-uri>
                    <uri>…<uri>
                    …
                    <uri>…<uri>
                </alt-uri>
                <domains>…</domains>
            <action>
            …
            <action>
            …
            </action>
    </actionspage>

ActivID AS 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. Copy the XML file to the AuthenticationPortal/config/templates/process folder.

    2. By default, this folder is not present so create it if necessary.

  2. Optionally, add the customization labels for the new authentication process template in the ActivID Authentication Portal branding configuration.

    3. Note: Authentication process templates can rely on customized language files.

    If labels are not found in the language customization file, then the system uses the labels provided in the authentication process template XML file.

    As a result, you need to add the elements you created in your new authentication process template to the portal customization files (a set of entries per required language).

    1. If you have not previously customized your deployment, manually create the _common_ and/or domain-specific folders using the default folder as a template.

    2. If it does not already exist, create the ac-4tress-portal_en.properties file in AuthenticationPortal/branding/_common_/ap folder.

    You can make a copy of the default file in the AuthenticationPortal/branding/default/ap folder.

  3. To customize the labels in another language, rename the properties file with the locale corresponding to the required language.

  4. In this properties file, add the labels for the new authentication process template using the following keys:

    • Global description: ai.samlidp.template.<TemplateName>.description
    • For each action (<ActionId> stands for the action id):
      Action name: ai.samlidp.template.<TemplateName>.<ActionId>.name
      Action description: ai.samlidp.template.<TemplateName>.<ActionId>.name

    5. For example, add the following labels for the new CH_SSP_CUSTOM template:

    Copy 
    ai.samlidp.template.CH_SSP_CUSTOM.description= Welcome. What do you want to do?
    ai.samlidp.template.CH_SSP_CUSTOM.1.name= Activate a New Token
    ai.samlidp.template.CH_SSP_CUSTOM.1.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.
    ai.samlidp.template.CH_SSP_CUSTOM.2.name= Manage an Existing Token
    ai.samlidp.template.CH_SSP_CUSTOM.2.description= View, update, test or discard any of my devices.
    ai.samlidp.template.CH_SSP_CUSTOM.3.name= Emergency Access
    ai.samlidp.template.CH_SSP_CUSTOM.3.description= Troubleshoot problem login in to applications or report lost, stolen or damaged device.

    Or, for example, add the following labels for the new CH_SSP_CUSTOM template in French:

    Copy 
    #CH_SSP_CUSTOM template customization
    ai.samlidp.template.CH_SSP_CUSTOM.description=Bienvenue. Que souhaitez-vous faire ?
    ai.samlidp.template.CH_SSP_CUSTOM.1.name=Activer un nouveau token
    ai.samlidp.template.CH_SSP_CUSTOM.1.description= Activer mon premier token (mobile ou clé) pour pouvoir m’authentifier à mes applications. Pour une réactivation, utiliser Gérer un token existant.
    ai.samlidp.template.CH_SSP_CUSTOM.2.name= Gérer un token existant
    ai.samlidp.template.CH_SSP_CUSTOM.2.description= Voir, modifier, tester ou désactiver un de mes tokens et en ajouter d’autres.
    ai.samlidp.template.CH_SSP_CUSTOM.3.name=Troubleshooter mon token
    ai.samlidp.template.CH_SSP_CUSTOM.3.description= Investiguer un problème d’authentification aux applications ou déclarer un token perdu, volé ou endommagé.

  5. Apply the customization package.

  6. Restart the ActivID AS applications.

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

  7. In addition, if you want to replicate the new authentication process template to other ActivID AS servers in your deployment:
    1. Create a customization package of the authentication process template you created above.

    2. Apply the customization package to each server hosting either the ActivID Authentication Portal and/or the ActivID Management Console.

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: