1 Introduction

With Kemp's 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.

1.1 Document Purpose

This document describes how to customize the login form when Form Based authentication is selected as the Client Authentication mode.

1.2 Intended Audience

This document is intended to be read by anyone who is interested in finding out how to customize the Kemp ESP authentication form.

2 Customizing the Login 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.

2.1 SSO Greeting Message

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 HTML code, so you can insert an image if required.

However, there are several characters that are not supported. These are the grave accent character ( ` ) and single quotes (''). 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.

2.2 SSO Image Set

The SSO Image Set option is only available if Form Based is selected as the Client Authentication mode. The SSO image sets available are:

Blank

Dual Factor Authentication

Exchange

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.

 

Exchange Form

The Exchange Form contains the Kemp logo.

 

Blank Form

The Blank Form does not contain the large 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.

2.2.1 Custom SSO Image Set Guidelines

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 Kemp Documentation site: https://kemptechnologies.com/loadmaster-documentation/. There is one template for regular login forms and one for dual factor authentication.

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:

imagesets/

<IMAGESETNAME>/

lm_initial.html

lm_logout.html

MANIFEST

...

lm_initial.html: The lm_initial.html is a dummy ESP login page which user can modify or use as it is. This page will be presented for authentication when user connects the ESP VS. The public/private option becomes available over 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 user can modify or use as it is. This page prompts when user successfully logout 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:

- imagesets/<IMAGESETNAME_1>/<files>

/<IMAGESETNAME_2>/<files>

- 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

- All other files defined in the file, for example image, CSS or Javascript files, can be used by the login and logout pages

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

2.2.2 Uploading a Custom SSO Image Set

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.

2.3 Backing Up and Restoring a Custom SSO Image Set

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.

2.4 Display Public/Private Option

Enabling this check box 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, which does not save their credentials locally.

References

Unless otherwise specified, the following documents can be found at http://kemptechnologies.com/documentation.

ESP, Feature Description

Last Updated Date

This document was last updated on 11 March 2022.