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) |
|
LDAP Password (LDAP Fallback/Passthrough) |
|
Security Questions and Answers (Employee Emergency Q&A) |
|
OOB Authentication (Out of Band) (Employee OOB Authentication) |
To be used for second step tiered-authentication. It does not require an Activation code, the OTP is sent by mail.
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) |
|
PKI Authentication (Citizen PKI Authentication) |
|
EMV Authentication |
|
Mobile push-based Logon Validation |
Legacy template for Push-Based Authentication support. It performs user Static Password authentication, then 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.
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.
- Create an XML file with a filename that includes the specific prefix to link it to the appropriate type of authentication policy.
-
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>
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.
Element | Description | Mandatory | Number of occurrences | Attributes |
---|---|---|---|---|
<configuration> |
The root element. |
Yes |
1 |
None |
<configuration> |
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> |
Describes a data involved in the authentication process (for example, the “user name” and the “static password”). |
Yes |
[2, 10] |
|
<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 |
-
Copy the XML file to the AuthenticationPortal/config/templates/gui folder of the customization package.
-
If you have not previously customized your deployment, manually create the _common_ and/or domain-specific folders using the default folder as a template.
-
Add the customization labels for the new authentication GUI template in the ActivID Authentication Portal branding configuration.
-
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).
-
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.
-
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).
Each entry must have its key ending with the name of the template. For example, add the following labels for the UP_MYTEMPLATE:
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
-
Declare the new authentication GUI template in the ActivID Management Console:
- 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).
-
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:Copyai.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
The original list is available in the default configuration file (ac-4tress-mgtcons_en.properties in ManagementConsole/branding/default/mc).
-
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:
ai.configuration.policies.saml.ftressidp.authpolicymapping.<TEMPLATE_NAME>
For example, add the following label for the UP_MYTEMPLATE:
Copyai.configuration.policies.saml.ftressidp.authpolicymapping. UP_MYTEMPLATE=My User/Password Template
-
Restart the ActivID AS applications.
-
Configure the authentication policies mapping with the new authentication GUI template using the ActivID Management Console:
After several minutes, the new authentication GUI template will be available in the ActivID Authentication Portal.
In addition, if you want to replicate the new authentication GUI template to other ActivID AS servers in your deployment:
-
Create a customization package of the authentication GUI template you created above.
-
Apply the customization package to each server hosting either the ActivID Authentication Portal and/or the ActivID Management Console.
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.
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.
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).
-
Create an XML file for the new authentication process template (for example, to customize the ActivID Self-Service Portal, CH_SSP_CUSTOM.xml).
-
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>
Element | Description | Mandatory | Number of occurrences | Attributes |
---|---|---|---|---|
<actionspage> |
Root element |
Yes |
1 |
|
<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] |
|
<actionspage> <actions> |
Contains the ordered sequence of actions. |
Yes |
1 |
None |
<actionspage> <actions> <action> |
Root element on an action. |
Yes |
[1, 10] |
|
<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.
|
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:
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 |
-
Copy the XML file to the AuthenticationPortal/config/templates/process folder.
-
Optionally, add the customization labels for the new authentication process template in the ActivID Authentication Portal branding configuration.
If you have not previously customized your deployment, manually create the _common_ and/or domain-specific folders using the default folder as a template.
If it does not already exist, create the ac-4tress-portal_en.properties file in AuthenticationPortal/branding/_common_/ap folder.
- To customize the labels in another language, rename the properties file with the locale corresponding to the required language.
-
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
- Global description:
-
Restart the ActivID AS applications.
- In addition, if you want to replicate the new authentication process template to other ActivID AS servers in your deployment:
- Create a customization package of the authentication process template you created above.
Apply the customization package to each server hosting either the ActivID Authentication Portal and/or the ActivID Management Console.
By default, this folder is not present so create it if necessary.
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).
You can make a copy of the default file in the AuthenticationPortal/branding/default/ap folder.
For example, add the following labels for the new CH_SSP_CUSTOM template:
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:
#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é.
After several minutes, the new authentication process template will be available in the Authentication Portal.
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: