Customizing Look and Feel of UAG

Erez Ben-Ari

February 2012

(For more resources on Microsoft Forefront UAG, see here.)

Honey, I wouldn't change a thing!

We'll save the flattery for our spouses, and start by examining some key areas of interest what you might want and be able to change on a UAG implementation. Typically, the end user interface is comprised of the following:

  • The Endpoint Components Installation page
  • The Endpoint Detection page
  • The Login page
  • The Portal Frame
  • The Portal page
  • The Credentials Management page
  • The Error pages

There is also a Web Monitor, but it is typically only used by the administrator, so we won't delve into that. The UAG management console itself and the SSL-VPN/SSTP client-component user interface are also visual, but they are compiled code, so there's not much that can be done there.

The elements of these pages that you might want to adjust are the graphics, layout, and text strings. Altering a piece of HTML or editing a GIF in Photoshop to make it look different may sound trivial, but there's actually more to it than that, and the supportability of your changes should definitely be questioned on every count. You wouldn't want your changes to disappear upon the next update to UAG, would you? Nor would you look the page to suddenly become all crooked because someone decided that he wants the RDP icon to have an animation from the Smurfs.

The UI pages

Anyone familiar with UAG will know of its folder structure and the many files that make up the code and logic that is applied throughout. For those less acquainted however, we'll start with the two most important folders you need to know—InternalSite and PortalHomePage. InternalSite contains pages that are displayed to the user as part of the login and logout process, as well as various error pages. PortalHomePage contains the files that are a part of the portal itself, shown to the user after logging in.

The portal layout comes in three different flavors, depending on the client that is accessing it. The most common one is the Regular portal, which happens to be the more polished version of the three, shown to all computers. The second is the Premium portal, which is a scaled-down version designed for phones that have advanced graphic capabilities, such as Windows Mobile phones. The third is the Limited portal, which is a text-based version of the portal, shown to phones that have limited or no graphic capabilities, such as the Nokia S60 and N95 handsets.

Regardless of the type, the majority of devices connecting to UAG will present a user-agent string in their request and it is this string that determines the type of layout that UAG will use to render its pages and content. UAG takes advantage of this, by allowing the administrator to choose between the various formats that are made available, on a per application basis. The results are pretty cool and being able to cater for most known platforms and form factors, provides users with the best possible experience. The following screenshot illustrates an application that is enabled for the Premium portal, and how the portal and login pages would look on both a premium device and on a limited device:

Customizing the login and admin pages

The login and admin pages themselves are simple ASP pages, which contain a lot of code, as well as some text and visual elements. The main files in InternalSite that may be of interest to you are the following:

  • Login.asp
  • LogoffMsg.asp
  • InstallAndDetect.asp
  • Validate.asp
  • PostValidate.asp
  • InternalError.asp

In addition, UAG keeps another version of some of the preceding files for ADFS, OTP, and OWA under similarly named folders. This means that if you have enabled the OWA theme on your portal, and you wish to customize it, you should work with the files under the /InternalSite/OWA folder. Of course, there are many other files that partake in the flow of each process, but the fact is there is little need to touch either the above or the others, as most of the appearance is controlled by a CSS template and text strings stored elsewhere. Certain requirements may even involve making significant changes to the layout of the pages, and leave you with no other option but to edit core ASP files themselves, but be careful as this introduces risk and is not technically supported. It's likely that these pages change with future updates to UAG, and that may cause a conflict with the older code that is in your files. The result of mixing old and new code is unpredictable, to say the least.

The general appearance of the various admin pages is controlled by the file /InternalSite/CSS/template.css. This file contains about 80 different style elements including some of the 50 or so images displayed in the portal pages, such as the gradient background, the footer, and command buttons to name a few. The images themselves are stored in /InternalSite/Images. Both these folders have an OWA folder, which contains the CSS and images for the OWA theme.

When editing the CSS, most of the style names will make sense, but if you are not sure, then why not copy the relevant ASP file and the CSS to your computer, so you can take a closer look with a visual editor, to better understand the structure. If you are doing this be careful not to make any changes that may alter the code in a damaging way, as this is easily done and can waste a lot of valuable time.

A very useful piece of advice for checking tweaked code is to consider the use of Internet Explorer's integrated developer tool. In case you haven't noticed, it's a simple press of F12 on the keyboard and you'll find everything you need to get debugging. IE 9 and higher versions even pack a nifty trace module that allows you to perform low-level inspection on client-server interaction, without the need for additional third-party tools.

We don't intend to devote this book to CSS, but one useful CSS element to be familiar with is the display: none; element, which can be used to hide any element it's put in. For example, if you add this to the .button element, it will hide the Login button completely. A common task is altering the part of the page where you see the Application and Network Access Portal text displayed. The text string itself can be edited using the master language files, which we will discuss shortly. The background of that part of the page, however, is built with the files headertopl.gif, headertopm.gif, and headertopr.gif. The original page design is classic HTML—it places headertopl on the left, headertopr on the right, and repeats headertopm in between to fill the space. If you need to change it, you could simply design a similar layout and put the replacement image files in /InternalSite/Images/CustomUpdate. Alternatively, you might choose to customize the logo only by copying the /InternalSite/Samples/ file into the /InternalSite/Inc/CustomUpdate folder, as this is where the HTML code that pertains to that area is located.

Another thing that's worth noting is that if you create a custom CSS file, it takes effect immediately, and there's no need to do an activation. Well at least for the purposes of testing anyway. The same applies for image file changes too but as a general rule you should always remember to activate when finished, as any new configurations or files will need to be pushed into the TMG storage. Arrays are no exception to this rule either and you should know that custom files are only propagated to array members during an activation, so in this scenario, you do need to activate after each change. During development, you may copy the custom files to each member node manually to save time between activations, or better still, simply stop NLB on all array members so that all client traffic is directed to the one you are working on.

An equally important point is that when you test changes to the code, the browser's cache or IIS itself may still retain files from the previous test or config, so if changes you've made do not appear first time around, then start by clearing your browser's cache and even reset IIS, before assuming you messed up the code.

Customizing the portal

As we said earlier, the pages that make up a portal and its various flavors are under the PortalHomePage folder. These are all ASP.NET files (.ASPX), and the scope for making any alterations here is very limited. However, the appearance is mostly controlled via the file /InternalSite/PortalHomePage/Standard.Master, which contains many visual parameters that you can change. For example, the DIV with ID content has a section pertaining to the side bar application list. You might customize the midTopSideBarCell width setting to make the bar wider or thinner. You can even hide it completely by adding style="display: none;" to the contentLeftSideBarCell table cell. As always, make sure you copy the master file to CustomUpdate, and not touch the original file, and as with the CSS files, any changes you make take effect immediately.

Additional things that you can do with the portal are removing or adding buttons to the portal toolbar. For example, you might add a button to point to a help page that describes your applications, or a procedure to contact your internal technical support in case of a problem with the site.

(For more resources on Microsoft Forefront UAG, see here.)

Portal application icons

Besides the graphics used by the various ASP pages, another common need is to have custom icons for applications. As you probably know, you can specify the icon name as part of any application's configuration, in the Portal Link tab.

However, keep in mind that you need to create four icons, and not just one: one file for the primary home-screen icon, a smaller version for the navigation bar, and another set of both for disabled applications. The disabled icons are used when UAG blocks access to the application, such as when a portal has RemoteApps published and is being accessed from Firefox. You can go ahead and inspect the /PortalHomePage/Images/AppIcons folder to see these existing default icons.

The following screenshot shows the setting that defines the application's icon URL, and the four types of icons that are used:

When creating your icons, you can use GIF, JPG or PNG formats, and while you can use any image size, it's best to use the native size, rather than letting the browser stretch the image files on screen.

Stretching images often leads to ugly results, so we recommend that you create the home-screen icons at 88 X 50 pixels, and the Nav-Bar icons at 16 X 16 pixels.

While the default home screen's background is white, the Nav-Bar is not, so make sure that your images have a background color that is similar to the Nav-Bar's background, or have a transparent one (JPG files can't do that, but GIF and PNG can).

Even though you specify only one icon filename in the Icon URL setting, UAG will automatically look for and use the following naming conventions for the other icons:

  • Normal icon: .gif
  • Normal disabled icon: _dis.gif
  • Nav-Bar icon: _icon.gif
  • Nav-Bar disabled icon: _icon_dis.gif

One thing to keep in mind is that if you would like to create a custom icon that pertains to a group of applications (for example, for all of your Generic web applications), you don't have to edit the Icon URL for all of them—simply create substitute icons using the same names as the default application icon uses, and put them in /PortalHomePage/Images/AppIcons/CustomUpdate. This is also suitable for certain applications that do not allow you to specify a custom icon, such as the Remote Desktop applications.

One exception to the preceding scenario is when publishing RemoteApp applications. UAG only has one generic icon for all RemoteApp applications, but you would typically prefer to have separate icons for each. To do this, you have to use a slightly different naming convention. UAG will automatically recognize any one of the four conventions:

  • ...png
  • ..png
  • ..png
  • .png

Customizing RemoteApp icons can be slightly more involved and an important step in this process is that you remove and re-add the RemoteApp application each time you change icons, followed by activation. Otherwise, UAG will fail to acknowledge the change and the default icons will remain.

Changing texts

The most popular look and feel customization going is customizing the text on the various pages. Almost all organizations need to change the generic This site is intended for authorized users only disclaimer with something more specific, and many also want to add custom info or instructions to that page. The various error messages that UAG spits out are also frequently changed too. Again there's nothing to prevent you from editing some of the ASP files directly to change the text shown, but as already mentioned it's a much safer bet to stick to the road and avoid supportability headaches.

The text we see is generated by ASP, but this text is actually called from a central XML file, which makes customizing the various verbiages seen throughout a very easy task. Texts that pertain to the admin pages are stored in /Von/InternalSite/Languages/en-US.xml, and texts that pertain to the portal itself are under /Von/PortalHomePage/Data/Languages/en-US.xml. The folders actually contain other files for other languages, such as German, Spanish, French, and more. When accessed from a system that is configured for another language (in the browser's language settings), UAG detects the settings and applies the appropriate language, if it has the corresponding files for it. If it doesn't, it will default to English, but you can add as many other languages as you like.

Adding a user interface language

Adding languages to the portal pages or in the drop-down list at login is another common requirement in making the look and feel much more personal. To add a language, clone one of the built-in files into the languages CustomUpdate folder, and edit the strings in it with Notepad, or any other text editor of your choice. Once done, rename it to reflect the language ID (for example, for Hebrew, you would use he-IL). Lastly, copy the file languages.xml into CustomUpdate, and add the language setting to it as you can see in the following screenshot. As a best practice, we would also suggest you only include lines that include changes to the language-specific file and remove everything else as this duplicates UAG's efforts when language data is being parsed.

One thing you may notice from the preceding screenshot is the CDATA (Character Data) section in some of the strings. CDATA is a special format that is used to insert non-text data into the strings. Since the ASP code pulls the strings directly into an HTML page, this means you can use this format to inject HTML code directly via the language file, and this is you see why?

The reason why this is so cool is because, other than simple HTML tags, you can also inject JavaScript in there. For example, you can add a very long terms of use text into a DIV with the style set to hidden (Style="display:none;"), and put in a script to unhide it when the user clicks on a button. Another creative idea would be to check the formatting of the username before the user submits the form, to make sure it matches your requirements (UPN versus domain\user),but you could even save the user's username or repository selection in a cookie, to make the future logins easier. The formatting for CDATA is as follows:

<![CDATA[ <any HTML code you desire!> ]]>

This is just one of the many examples, but the fact is you would always put security first, and way before usability or aesthetics. Having so much flexibility is great, but we certainly wouldn't recommend using careless techniques to reduce the time and effort it takes a user to login and authenticate.

This same principle can be used for any text string, anywhere. Keep in mind that modern HTML supports things, such as the position:absolute style, which allows you to place your elements almost anywhere on screen. For example, customize string number 105 as follows:

<String id="105" _locID="105">User name:<![CDATA[<p

your username&nbsp;using&nbsp;the&nbsp;format <B>user@domain</p>]]>


The preceding code would result in the text appearing on the right as shown in the following screenshot:

This is not perfect because positioning is measured from the edge of the screen, so people using IE with a different display-resolution or with the IE window floating may see the text floating somewhere else, unless your CSS code is designed to address this. It's also important to check a user's browser and add compatibility code, if required. These techniques require advanced knowledge of HTML, CSS, and JavaScript, and are beyond the scope of this book.

Naturally, you don't have to limit yourself to HTML and JavaScript. You can also incorporate animated GIFs, or even Java, Flash, and Silverlight elements in your custom pages. Keep in mind that UAG does not support the latter two, because it cannot parse and HAT links in them. However, if they are used for visual effects only, it should be perfectly fine. If properly designed, Java, Flash, and Silverlight can be made to work seamlessly with UAG. For example, you can embed the UAG HAT signatures in links that are inside such files, or use relative URLs with paths that UAG will be able to recognize even without the HAT signature.

One thing to keep in mind is that if you put new files onto UAG to use as part of your customization (such as Silverlight files), the default URL Set may not accept them, and may throw a You have attempted to access a restricted URL error. To work that out, simply add the appropriate URL Set rules to the Advanced Trunk Configuration.

Hardcoding signatures into files can be a bad idea, as the HAT signature may change if the backend server properties changes, causing your files to be out of sync with UAG. This should be taken into consideration, to avoid breaking things unexpectedly, and as a result of some network engineer being too independent.

Another tip for text changing

An oft-missed option with UAG is Prompt users before retrieving information from endpoint, which is available under the Endpoint Access Settings tab in the Advanced Trunk Configuration screen. This page shows a notification for the user to allow or disallow the endpoint components to collect information about his/her computer. This option in itself is of less interest to us here, but it is one more page that could be customized if absolutely necessary(/InternalSite/Inc/ And although we wouldn't encourage changing this file, a good example of its use could be to add a disclaimer, forcing the user to consciously acknowledge the company's terms of use before proceeding into the site.

Portal selection for clients

As we noted earlier, UAG comes with three types of portals. UAG has logic to detect client and browser types based on the user agent string that each browser sends. According to this, UAG decides which portal to send to the user, but it may get it wrong. For example, UAG may not recognize a certain phone or tablet's agent, and direct it to the wrong portal (a mobile portal on a 10-inch tablet would look weird, and a PC portal on a phone would be quite impossible to use). If you run into this sort of situation, you can customize UAG to recognize your devices differently.

Before continuing, please bear in mind that changes in this area do not extend UAG's supportability boundaries, which limits the types of client platforms that are officially supported by Microsoft. Technically speaking, you can access the UAG portal with almost any browser in the world, even HyperLink(), but the results may be unpredictable, and many application types may not work if connecting from a client that UAG isn't geared up for.

Another thing to keep in mind is that these files are unique in the fact that they don't support UAG's standard CustomUpdate scheme, which means you will have to edit the original files. This also means that when installing updates to UAG, your additions may get overwritten, so be sure to back up your edited files once you have stabilized the server. After an update, you may be able to simply restore your version of the files, but we would recommend you redo the customization (that is, open the new files and insert the custom lines into them). This is, of course, because the updated files may contain new and enhanced code that may be integral to its functionality.

To edit the detection, open the files \von\PortalHomePage\Web.config and \von\InternalSite\Web.config (you should modify both), and look for the section DetectionExpression. The syntax is pretty self-explanatory—the list contains multiple Detection Expressions, which all relate to different client platforms that UAG has awareness of. Then, the four portal types have their own expressions, which refer to the other expressions.

We said earlier that there are three, but there are actually four portals, with the fourth type being LimitedPC, which is shown on non-Windows/IE computers.

For example, let's say you want to configure UAG to detect the Samsung Galaxy tablet, and treat it as a phone, rather than a PC. The user-agent string for the galaxy is:

Mozilla/5.0 (Linux; U; Android 2.2; en-us;
SGH-I987 Build/FROYO) AppleWebKit/533.1 (KHTML, like Gecko)
Version/4.0 Mobile Safari/533.1

There are actually several variations of the Galaxy, so your model may be slightly different than the preceding one.

All you have to do is edit the expression PremiumMobile and add a command to accept the Galaxy, based on its model number of SGH-I987, which is listed in the user-agent string. The built-in expression for the premium mobile portal looks for various strings already, such as iPhone and Android, so just append OR UserAgent Contains "SGH-I987" at the end of the expression as shown in the following screenshot:

There is more than one way to change or add to UAG's detection mechanism—you can also create a new expression to detect a certain device, and give it an ID. Then, change one of the other expressions to accept the new ID. It may not be easy, so the best advice we can give here is to analyze the user agent carefully, as well as the detection expressions, so you can know for sure how exactly UAG arrives at its decision when distinguishing device types.


In this recipe, we discovered the world of visual customizations, and the various ways they can be applied. We also discussed creative ways to get UAG to look the way you need it to, and explored which are the best ways to achieve it.

Further resources on this subject:

You've been reading an excerpt of:

Mastering Microsoft Forefront UAG 2010 Customization

Explore Title