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).
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.
Nothing to exciting yet, if you want to add more form styles you can add them on the SSO page.
But how do you create a new form?
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:
- 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.
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.
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 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>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.
- These variables contain the error messages, feel free to customize these.
- Include the lm_sso.js file containing scripts needed for ESP. This files is provided by Kemp.
- In the form tag you shouldn’t change the “method“, “action” and “id” tag. These are settings needed to have the ESP working correctly.
- 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.
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>
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.
Don’t forget, you can get a free Kemp Loadmaster from freeloadbalancer.com.