Customising UAG - InternalSite / Login.asp

One of the first requirements I addressed was the customisation of the login pages of the site.  Initially, Microsoft support stated that customisation was not permitted, later dismissed by Professional Services, and on the contrary was encouraged by them.

The aim of this post is to give a very high level summary of what I did – the aims of the work were:

o   to corporately brand the page properly and completely remove the UAG branding. 

o   to ensure consistent look and feel to corporate standards

o   to make a first attempt of customising UAG

I then got MS PS to verify how I went about the task to be sure I did it right.

I make a lot of assumptions here about basic knowledge of UAG as I could write forever, but within the first hour or two of customising a deployment these assumptions will be second nature.

Essential skills: good understanding of HTML; javascript and (classic) ASP are a benefit but you can just go around them otherwise

First the basics of customisation:

o   Technet documents to a degree how to modify UAG’s login page and other standard pages – this is all done in this case by modifying files inside the von/InternalSite/ directory inside the UAG Program Files folder (I encourage you to read up on inc files and CustomUpdate in Technet if this is totally new to you) 

o   In short, most files can be modified but never update the original file – instead take a copy of the version of the file in the ‘samples’ directory if there is one or copy the original, and place it in the CustomUpdate directory (originals get rewritten by patches and backups do not include them).  If you want every published application to use this, leave the name the same.  If you want it used for one site, prefix the filename with the trunk name, then 0 (for http trunks) and 1 (for https trunks) eg MyTrunk0Login.asp. 

o   Beware of copying more unusual original files such as Validate.asp – these often have headers that say ‘if a custom version exists, use the custom version, otherwise do what is below”.  Remove this code for custom versions.

o   While most files can be modified, there is generally more than one way to make the change.  Eg A lot of the content is defined through XML files, which the ASP pages automatically read, and inc files.   You could change the ASP file, the XML or the INC and achieve the same thing

o   As a primer on the subject, read (but do not take as verbatim) the IAG guide on customisation found at http://www.isaserver.org/tutorials/Customizing-IAG-2007-Portal-Pages.html.  While it is for the old version, IAG, and many areas have changed in UAG, the principles remain the same

o   I am not going to do a full tutorial here on this subject unless there is sufficient demand

So – to login.asp.

The file is pretty complicated but you can, if you are careful, edit it heavily:

o   The HTML content is OK to edit, move this around as much as you want.   This is useful for adding content and playing with layout

o   The ASP sections can be modified but make sure you understand ASP before you go playing.  One mistake and you get a very unhelpful 500 error with no way of debugging that I have found

o   The inserted components such as languages and disclaimers can be removed, but if you are not sure you definitely want to remove them, try to do it ‘the UAG way’ if you can find out how: languages for example can be disabled in the Advanced Trunk Configuration in the UAG console.

o   ...and as far as I can work out, there are some things that just cannot be done ‘the UAG way’!  MS PS just use Dreamweaver and make their changes directly

o   As much as you can, modify the CSS file not the ASP file.  Microsoft use the CSS file extensively – not quite so much here but if you modify the portal prepare for some serious CSS goodness.

o   Firefox plus design plugins such as Firebug are a godsend in this job, as they highlight where in the code page elements exist,  making the task many times easier

o   If you go mad, follow the advice I was given and get MS Support to verify they will support the changes, and keep the reply email safe

o   DO NOT change the name of the login.asp file when you place it in the CustomUpdate folder except to add the trunk name and 0/1.  If you do change the file name, you must update the URL rules in the Advanced Trunking area of the UAG console

o   If you change the file name and do not change the URL rules, the following happens:

A client browser loads and accesses the site published in UAG using its normal address (thus accessing login.asp), it redirects as usual to the same address with /?uniquesig followed by the UAG’s signature and the other normal parameters.  Normally this is fine and the login box shows, but when the URL rules are not updated the UAG error page comes up with an “You have attempted to access a restricted URL. The URL contains an invalid path”.  If you access the address of the site again (deleting the uniquesig onwards, so it is just the site address) it then shows the login box.

o   Many thanks to Phil @ MS Support for pointing this out.  What I learnt from this is that URL rules apply only to explicit addresses passed to the browser, not to internal content loaded by the ASP execution – ie it applies to URLs requested by a browser, but not to pages generated through ASP includes.

The exact changes I made are far too lengthly for this post; no doubt you will not do exactly the same anyway.

o   I deleted a lot of the page, removing much of the form content on the page to just leave the username and password fields, and the login button (the text of which I replaced with an image manually)

o   I also moved the logo.inc include to go under the topmost table tag as I wanted the (sizable) logo to sit on the top of the page and not small, centered and just above the login fields.

Your changes effect the site immediately, there is no need to continually activate the UAG configuration.

--Chris

[MS PS = Microsoft Professional Services]