Customizing SSO Authentication Forms
Progress Kemp's Edge Security Pack (ESP) simplifies the secure publishing of applications with pre-authentication of clients and Single Sign-On to improve the user experience. ESP can be fully integrated into your current authentication and authorization directories, including Microsoft Active Directory.
With the Progress Kemp Edge Security Pack (ESP), it is possible to specify how clients, which are connecting to the LoadMaster, are authenticated. One of the options is Form Based authentication. When this option is selected, clients must enter their user details within a form to be authenticated on the LoadMaster.
When Form Based authentication is enabled, it is possible to customize the login form that the user sees.
For more information on ESP, and the various methods of authentication, refer to the ESP, Feature Description.
This document describes how to customize the login form when Form Based authentication is selected as the Client Authentication mode.
This document is intended to be read by anyone who is interested in finding out how to customize the Progress Kemp ESP authentication form.
There are two ways to customize the ESP login form:
Using the SSO Greeting Message text box
Using a Single Sign On (SSO) image set
The SSO Greeting Message text box is an easy way of adding some text to the login form.
The SSO image set option should be used for further customizations, such as configuring the form to have a desired look and feel.
Refer to the relevant section below to find out more.
The login form can be customized by adding text. To do this, follow the steps below in the LoadMaster Web User Interface (WUI):
1. In the main menu of the WUI, select Virtual Services and View/Modify Services.
2. Click Modify on the relevant Virtual Service.
3. Expand the ESP Options section.
4. Ensure that ESP is enabled.
5. Ensure that the Client Authentication mode is set to Form Based.
6. Enter the text that you would like to appear on the form within the SSO Greeting Message text box.
7. Click the Set SSO Greeting Message button.
The message can have up to 255 characters.
An example Exchange login form with an SSO greeting message is shown in the screenshot above.
The SSO Greeting Message field accepts ASCII characters and HTML code, so you can insert an image if required.
The SSO Greeting Message displays up to 255 characters. Any ASCII character is accepted and will be displayed in the message, with two exceptions: the grave accent character ( ` ) and the single quote ( ’ ).If a grave accent character is used in the SSO Greeting Message, the character will not display in the output, for example a`b`c becomes abc. If a single quote is used, users will not be able to log in.
In addition to ASCII characters, HTML-encoded characters are also accepted and can be used to display non-ASCII characters in the login form; just type HTML-encoded characters into the SSO Greeting Message text box in the LoadMaster. For example, for the letter Ä, you must type the HTML-encoded code for this letter, for example, Ä. For further information, please see: List of XML and HTML character entity references.
The SSO Image Set option is only available if Form Based is selected as the Client Authentication mode. The SSO image sets available are:
Dual Factor Authentication
Dual Factor Authentication - Customizable
French Canadian - Blank
French Canadian - Exchange
Brazilian Portuguese - Blank
Brazilian Portuguese - Exchange
Any custom SSO image sets which have been uploaded
When using the Exchange image set, you must select the image set in the LM_Auth_Proxy, OWA, and ECP SubVSs.
The Exchange Form contains the Progress Kemp logo.
The Blank Form does not contain the large Progress Kemp logo.
Dual Factor Authentication
The Dual Factor Authentication form contains four fields - two for the remote credentials and two for the internal credentials.
Remote Credentials are credentials that are used to authenticate against remote authentication servers such as RADIUS, before allowing the user to authenticate against Domain Servers such as Active Directory servers.
Internal Credentials are credentials that are used to authenticate against the internal domain servers such as Active Directory Servers.
If the Authentication Protocol of the relevant SSO Domain is set to RADIUS and LDAP, the SSO Image Set must be set to Dual Factor Authentication.
It is possible to add your own SSO image set to customize the look and feel of the login form. The custom SSO image set must be in the format of a .tar file. Template .tar files are available from the Progress Kemp Support site: Single Sign-On Custom Images. There is one template for regular login forms and one for dual factor authentication.
After you download the file, you must unzip it before you can upload it to the LoadMaster.
These templates can be modified to gain the desired look and feel. Guidelines on the tar file are below:
- The .tar file should have the following folder structure:
lm_initial.html: The lm_initial.html is a dummy ESP login page which you can modify or use as is. This page will be presented for authentication when you connect to the ESP Virtual Service. The public/private option becomes available on the ESP login page if Display Public/Private Option is enabled. By default, this option is enabled.
lm_logout.html: The lm_logout.html is a dummy ESP logout page which you can modify or use as is. This page prompts when you successfully log out from ESP service.
When compressing the .tar file, please ensure to compress the imagesets folder, not the folder above or beneath it.
- Multiple image sets can be included:
- The name that you specify as <IMAGESETNAME_*> is the name that will appear in the SSO Image Set drop-down list in the WUI. This name can contain Unicode characters.
If the name of the custom SSO image set is the same as one of the default SSO image set names, the default one has precedence.
- All image set resources should contain non-encoded characters, that is, ASCII.
- The full list of required files for the image set is as follows:
- A file called MANIFEST is mandatory. This file should contain a list of files that exist in the directory that should be loaded as part of the set. If the MANIFEST file does not exist, the image set will not work. Lines in this file can be commented out by adding # to the start of the line. Blank lines are ignored. The last line of the MANIFEST file must be a new line.
- The first uncommented line should contain the file for the main login page
- The second uncommented line should contain the file for the logout page
- If a listed file is missing, it will simply not be present on the page. For example, if a line in the MANIFEST refers to image.jpg and that image file is missing from the tar, it will be a broken image on the page.
The logical format of the main login page cannot be changed. If the format is not maintained, problems will occur. The formatting and any CSS can be changed at will.
- A file called INFO is read. This is a simple text file which contains a description of the image set and perhaps a version number. The contents of this file are displayed on the admin WUI to help identify which package/version has been installed. For example, this could contain version information.
The INFO file is not mandatory. If it does not exist or if it is blank, only the installed date is displayed in the WUI.
- The maximum size restriction on images is approximately 1 MB. This is dependent on the amount of space on /tmp for storing the file as it is being downloaded. There is also an additional limit for how much space is available on the flash (the 512 MB boot partition). Multiple large image sets can cause problems.
- Image file names can be a maximum of 31 characters long.
- The syntax for adding an image to a custom authentication form is as follows:
<img src=URL width=NN height=NN>
Replace URL with the URL of the image.
Replace NN for width and height with the desired values.
- If a package is installed multiple times, the older packages are overwritten.
- It is the responsibility of the package builder to verify that all components included are valid. A missing file will not be displayed. Broken pages may cause problems.
To upload the custom SSO image set to the LoadMaster, follow the steps below in the LoadMaster WUI:
1. In the main menu, select Virtual Services and Manage SSO.
2. Click Choose File.
3. Browse to and select the .tar file.
4. Click Add Custom Image Set.
After adding the file, the supplied image set(s) is listed on this page. It will also be available to select in the SSO Image Set drop-down list in the ESP Options section of the Virtual Service modify screen.
You can rename an image set by renaming the folder within the imagesets folder. After uploading, the new image set name is displayed in the SSO Image Set drop-down list.
Any custom SSO image sets that exist on the LoadMaster are contained in any LoadMaster backups that are taken. They are restored when VS Configuration is selected when restoring a backup file.
Enabling the Display Public/Private Option check box in the ESP Options section of the Virtual Service modify screen will display a public/private option on the ESP login page. Based on the option the user selected on the login form, the Session Timeout value is set to the value specified for either public or private in the Manage SSO domain screen. If the user is on a public or shared computer, they should use the default option (This is a public or shared computer), which does not save their credentials locally.
This document was last updated on 28 September 2022.