Custom login forms with Kemp

Introduction

If you’ve worked with the loadbalancers from Kemp before you’ve probably also noticed the ESP (Edge Security Pack) functionality. If you haven’t, read this and this while I get a cup of coffee. If you have heard about it you can also have something to drink.

As you probably know you can use the ESP functionality to have your users log in using many different authentication protocols among which Kemp recently added SAML.

Of course the authentication protocols are the most interesting but in this blog I’m focussing on the first thing a user sees when trying to login to your service: The login page (assuming you are using form based authentication).

Overview

Let’s start with a short overview on how the custom forms work. There are a few preconfigured forms available from Kemp so you don’t have to create login forms which look like Exchange from scratch. You can choose which form to use from the ESP config on a VS.

ESP configuration in VS
ESP configuration in VS

Nothing to exciting yet, if you want to add more form styles you can add them on the SSO page.

SSO management page
SSO management page

But how do you create a new form?

Form creation

Just to reassure you, you don’t need any python, xml or some obscure vendor proprietary scripting language. Just some html, javascript and an old fashioned text-editor, even notepad/vi will do.

Directory structure

Create a directory named “imagesets“, in this directory you can create subdirectories which will contain your own very personal login forms. The name of the subdirectory will also be the display name of your form in the WUI.

If you would create the following directory structure:

  • imagesets
    • Custom Form 1
    • Custom Form 2

And tar the “imagesets” directory (yes, it must be a tar file) it will show up in the WUI as in the image below after uploading it.

Custom image set overview
Custom image set overview

Mandatory files

There 3 files which must be present in your custom form subdirectory:

  • MANIFEST (that is the actual filename)
  • login html page, naming is unrestricted
  • logout html page, naming is unrestricted

Without these files your form will not work.

MANIFEST

The “MANIFEST” is exactly that, a manifest for the files which are needed for your custom form. In this file, which is just plain text, you put the file names of each file you use. If a file isn’t in the manifest the loadbalancer will return a HTTP 403 error when the user tries to access it.
Also, don’t forget to add a blank line at the end!. This will save you an hour of troubleshooting later on.

The first and second line are reserved for the login and logout pages. The names don’t matter but the file on the first line is used as login page and the file on the second line is used as logout page.

The login and logout page are normal html pages, let’s name the files “login.html” and “logout.html“. In the pages we’ll use an image “logo.png”. The “lm_sso.js” file contains javascript provided by Kemp to ensure proper working of the ESP.

The contents of your “MANIFEST” would look like this:

login.html
logout.html
lm_sso.js
logo.png
*BLANK LINE HERE*

Notice the last line, this line should be empty but make sure there is a blank line.

login.html and logout.html

Below are the html codes of the pages.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; CHARSET=utf-8">
    <title>Login @ VKNIT</title>
    <meta content="NOINDEX, NOFOLLOW" name="Robots">
	<script>
		// Support functions for SSO.
		//
		// Copyright (c) 2014 KEMP Technologies
		//
		//ident "$Id: lm_sso.js 14186 2016-11-23 12:32:03Z phil $ phil"
		//
		var xx_msg10 = "Login Failed - The security service has blocked your request. Please contact your System Administrator.<br><br>";
		var xx_msg11 = "Login Failed - Please make sure that your Username and Password are correct, and then try again.<br><br>";
		var xx_msg15 = "Enter New Passphrase:";
		var xx_msg17 = "Re-Enter Pin:";
	</script>
	<script type="text/javascript" src="/lm_auth_proxy?LMimage=lm_sso.js"></script>
</head>
<body onload='sso_setup("%s", "%s", "%s", %s, %s, %s);'>
	<noscript>
		<div id="dvErr">
			<table cellpadding="0" cellspacing="0">
			<tr>
				<td style="width:100%">To use LoadMaster ESP Login, javascript must be enabled in your browser.</td>
			</tr>
			</table>
		</div>
	</noscript>
	<form action="/lm_auth_proxy?LMLogon" method="post" id="logonForm" autocomplete="off" onSubmit="return save_username(this.username, this.pubpriv);">
		<input type="hidden" id="curl" name="curl" value="">
		<input type="hidden" id="curlid" name="curlid" value="">
		<input type="hidden" id="curlmode" name="curlmode" value="0">
		<table align="center">
			<tr>
				<td colspan="2" align="center" id="ssomsg"></td>
			</tr>	
			<tr>
				<td colspan="2" align="center" id="badmsg"></td>
			</tr>	
			<tr>
				<td colspan="2" align="center">
					<img src="/lm_auth_proxy?LMimage=logo.png" width="200px" height="140px">
					<strong>Login</strong>
				</td>
			</tr>
			<tr>
				<td>
					User: <input class="txt" id="username" name="username" type="text"/>
				</td>
				<td>
					Pass: <input class="txt" id="password" type="password" name="password" autocomplete=off required maxlength=128 />
				</td>
			</tr>
			<tr>
				<td colspan="2" align="center">
					<input type="submit" value="Log On" name="submit" /> 
				</td>
			</tr>
		</table>
	</form>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; CHARSET=utf-8">
    <title>Logged offVKNIT</title>
</head>
<body>
Thanks for visiting, close your browser. 
</body>
</html>

As you can see, “logout.html” is nothing more than an exit message. Put anything in there you want, you could redirect them back to you main site or just leave them with a message saying it’s safe to shutdown their computer now.

The “login.html” has some more restrictions which I will go over.

But first a general tip, you can insert links to other domains outside like you would usually do. If you are using files you have included in your custom form, you have to use  “/lm_auth_proxy?LMimage=filename“. You cannot access the files directly but the “lm_auth_proxy” script will return the requested file assuming it is on the “MANIFEST” list.  For examples check lines 19 and 44.

Below is an overview with the lines containing important codes.

  • 7-18
    • These variables contain the error messages, feel free to customize these.
  • 21
    • Include the lm_sso.js file containing scripts needed for ESP. This files is provided by Kemp.
  • 22-30
    • If javascript is not enabled in the user browser ESP will not function, these lines will inform the user if javascript is not enabled.
  • 31
    • In the form tag you shouldn’t change the “method“, “action” and “id” tag. These are settings needed to have the ESP working correctly.
  • 32-58
    • In the form you shouldn’t change the “id” and “name” tags because these are used in the processing of the login request by the Loadmaster.  You can change the “value” tags defining the default value.

This is a very basic example of a custom login form, the objective is to show only the necessary elements. You can add everything you like and create the most wonderful pages as long as you have these elements in your page.

Simple custom login form
Simple custom login form

Optional files

INFO

The “INFO” file isn’t mandatory, you can put information about the custom form in this file which will be shown in the WUI. You don’t have to include the “INFO” in your manifest file and you can use HTML code.

Below an example “INFO” file and the result in the WUI.

Created by Niels van Kampen <br>
<a href="http://www.vknit.nl" target="_blank">www.vknit.nl</a>
INFO file result in the WUI
INFO file result in the WUI

Uploading

Be prepared to do this step a lot when designing your login form. Because of the script that fetches the needed files for your form like the images you can’t open the page locally. You could change all references to files when testing locally to work around this but you would have to change all the references back when uploading. Either way, it’s not a very friendly way of designing your forms.

When you are ready to upload your own login form go back to the top directory (“imagesets“). Use a tool like 7Zip to compress the “imagesets” folder in a tar file.
Go to the Loadmaster WUI and on the “Manage SSO” on the bottom of the page you can find the option to add a “Custom Image Set“. Browse to the tar file and hit the upload button, you should see login form appear above. The Loadmaster will automatically overwrite any existing login forms with the same name.

If your login form has the same name as a preconfigured one the Loadmaster will use the preconfigured one.

Next, go to your ESP VS and you can select your own custom login form in the SSO Image Set option.

Select your own custom login form
Select your own custom login form

Reference

Kemp Custom Authentication Form

Kemp Edge Security Pack

Kemp example files

Don’t forget, you can get a free Kemp Loadmaster from freeloadbalancer.com.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.