Microsoft ISA 2006 web page customisation How to Guide

From Swivel Knowledgebase
Jump to: navigation, search


Microsoft ISA 2006 web page customisation How to Guide

NOTE: if you need to be able to support pass-through support for non-PINsafe users, the following article is insufficient. The current recommendation is to start with the files provided with the PINsafe ISA filter, and to customise them as required. Please contact support@swivelsecure.com for more details. Use the following article only if you do not need support for non-PINsafe users.

Overview

This is a brief outline of how to go about customising your forms-based authentication web pages in ISA server to support PINsafe authentication. It is assumed that you are reasonably familiar with modifying HTML pages.


Web Page Customisation

Install the ISA filter

First of all, you should install the latest version of the PINsafe ISA filter for ISA Server 2006, see Microsoft_ISA_2006_Integration. This includes customised pages for Outlook Web Access (OWA) and for general web access (the documentation specifically references Sharepoint, but it will work for other web applications).

You should only need to use this document if you wish to customise these pages further, or if you already have customised authentication pages to which you wish to add PINsafe functionality.


Obtain the ISA login pages

If you have not already got a customised set of ISA login pages, the simplest way is to make a copy of the entire contents of C:\Program Files\Microsoft ISA Server\CookieAuthTemplates\ISA. This folder contains 3 sub-folders: HTML, cHTML and xHTML. The latter two are for mobile standards, which PINsafe does not currently support, principally because those standards do not support JPEG images, which is the format that TURing images are generated in, so only the HTML folder is of interest. The copy should be made into a folder under C:\Program Files\Microsoft ISA Server\CookieAuthTemplates. The name of the folder should correspond to the name you enter in the custom form name in the listener properties. Within this folder, 4 files potentially need to be modified: strings.txt, usr_pcode.htm, usr_pwd.htm and usr_pwd_pcode.htm. Additionally, if international support is required, other strings.txt files will need to be modified. These files are under the nls sub-folder, one for each language. Note that, for international characters to be displayed correctly, the strings.txt file must contain Unicode characters, so you will need to use a text editor that supports reading and saving Unicode files (e.g. NOT Notepad).

The strings.txt file supplied in the pinsafeWeb (or pinsafeOWA) folder of the PINsafe ISA filter installation should be sufficient for your needs, unless you have added other customised strings to your web pages.

Note also that if you have added custom images and/or stylesheets, you will need to include them in the new custom folder.

Customising the web pages

It is possible to change the logo displayed at the top of the login page. The page may look like this:

Original look of ISA login page.

The image shown here at the top is in GIF format and is 500x115 pixels. On a 32-bit machine the picture can be found in "C:\Program Files\Microsoft ISA Server\CookieAuthTemplates\PINSafeOWA\HTML" - if the ISA server was installed to a non-standard location then this will not be the location. The file name of the logo is lgnTop.gif.

In order to update the picture for display you can simply substitute a new logo of exactly the same format and size then restart the ISA service to complete the installation of the new logo. This should then display the next time the page is accessed. The end result should look like this:

Updated look of the ISA login page.
Troubleshooting

If the page is requested by a refresh it is possible that the browser will display a cached version of the site. Clearing the cache within your browser may fix this.

If the logo is not of the same format (GIF) or of the same size (500x115pixels) then it may fail to display correctly.

If the name of the new image differs in case to the original then it may fail to load correctly.

When swapping the images it is recommended that you rename the old picture file and add the extension ".old". This will allow you to easily revert the image should the need arise.

Edit the strings.txt file

The entries added for PINsafe are:

L_OTC_Text = “One Time Code:”

L_StartSession_Text = “Start Session”

These are respectively the labels used for the one-time code text box and the TURing image request button. You can change these values (to the right of the = sign) to match your requirements, but ensure that the labels (to the left of the = sign) are as shown.

If you need to customise your pages for other languages, look in the nls sub-folder and find the sub-folder matching the language you need to use. Add strings with the same names as those shown above to the strings section. As noted above, please ensure that the files are saved as Unicode text.

Depending on what authentication method you are using, you may not need to modify all three of the login pages, as explained here:

  • usr_pwd.htm is used for Active Directory plus PINsafe AgentXML authentication.
  • usr_pcode.htm is used for RADIUS authentication as the ONLY form of authentication (i.e. when no Active Directory authentication is required).
  • usr_pwd_pcode.htm is used when Active Directory authentication is used in conjunction with PINsafe RADIUS authentication.

The other 3 pages all need very similar modifications: they need a text box for the one-time code, a button to display the TURing image, a place to display the TURing image and the JavaScript necessary to display the image.

Starting with the last item, the following JavaScript should be sufficient: 

   function onClickStartSession()
   {
       img = document.getElementById("PINsafeImage");
       username = document.getElementById("username");
 
       if ((img != null) && (username != null) && (username.value != ""))
       {
           var usernameValue;
 
           psn = username.value.indexOf("\\");
           if (psn != -1)
               usernameValue = username.value.slice(psn + 1);
           else
               usernameValue = username.value;
 
           img.src = "/PINsafeISAFilter.dll?username=" + usernameValue +
                     "&random=" + Math.round(Math.random()*1000000);
           img.style.display = "block";
       }
   }

Note that, for usr_pwd_pcode.htm only, the fourth line should read 

       username = document.getElementById("userid");

For the one-time code text box, both the id and the name attributes of the input field should be set to “otc”: 

 <input id="otc" type="password" name="otc" />

For its label, use the value @@L_OTC_Text as the label text. This will be replaced by the label you defined in strings.txt: 

 <label for="otc">@@L_OTC_Text</label>

The button to display a TURing image should have an onclick event of “onClickStartSession();”, and a value (label) of “@@L_StartSession_Text”: 

 <input id="StartSession" type="button" value="@@L_StartSession_Text" name="StartSession" onclick="onClickStartSession();"/>

Finally, the placeholder for the TURing image should have an id of “PINsafeImage”, and initially set to be invisible: 

 <img id="PINsafeImage" style="display:none;" />
Retrieved from "https://kb.swivelsecure.com/w/index.php?title=Microsoft_ISA_2006_web_page_customisation_How_to_Guide&oldid=2433"