Home Cloud & Networking Mastering Microsoft Forefront UAG 2010 Customization

Mastering Microsoft Forefront UAG 2010 Customization

By Erez Ben-Ari , Rainier Amara , Erez Y Ben
books-svg-icon Book
eBook $32.99 $22.99
Print $54.99
Subscription $15.99 $10 p/m for three months
$10 p/m for first 3 months. $15.99 p/m after that. Cancel Anytime!
What do you get with a Packt Subscription?
This book & 7000+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook + Subscription?
Download this book in EPUB and PDF formats, plus a monthly download credit
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook?
Download this book in EPUB and PDF formats
Access this title in our online reader
DRM FREE - Read whenever, wherever and however you want
Online reader with customised display settings for better reading experience
What do you get with video?
Download this video in MP4 format
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with video?
Stream this video
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with Audiobook?
Download a zip folder consisting of audio files (in MP3 Format) along with supplementary PDF
What do you get with Exam Trainer?
Flashcards, Mock exams, Exam Tips, Practice Questions
Access these resources with our interactive certification platform
Mobile compatible-Practice whenever, wherever, however you want
BUY NOW $10 p/m for first 3 months. $15.99 p/m after that. Cancel Anytime!
eBook $32.99 $22.99
Print $54.99
Subscription $15.99 $10 p/m for three months
What do you get with a Packt Subscription?
This book & 7000+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook + Subscription?
Download this book in EPUB and PDF formats, plus a monthly download credit
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with a Packt Subscription?
This book & 6500+ ebooks & video courses on 1000+ technologies
60+ curated reading lists for various learning paths
50+ new titles added every month on new and emerging tech
Early Access to eBooks as they are being written
Personalised content suggestions
Customised display settings for better reading experience
50+ new titles added every month on new and emerging tech
Playlists, Notes and Bookmarks to easily manage your learning
Mobile App with offline access
What do you get with eBook?
Download this book in EPUB and PDF formats
Access this title in our online reader
DRM FREE - Read whenever, wherever and however you want
Online reader with customised display settings for better reading experience
What do you get with video?
Download this video in MP4 format
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with video?
Stream this video
Access this title in our online reader
DRM FREE - Watch whenever, wherever and however you want
Online reader with customised display settings for better learning experience
What do you get with Audiobook?
Download a zip folder consisting of audio files (in MP3 Format) along with supplementary PDF
What do you get with Exam Trainer?
Flashcards, Mock exams, Exam Tips, Practice Questions
Access these resources with our interactive certification platform
Mobile compatible-Practice whenever, wherever, however you want
  1. Free Chapter
    Customization Building Blocks
About this book
While UAG is built to integrate with many environments and publish dozens of application types, many organizations require a certain level of customization to meet their needs. With this book in hand, you will be equipped to deal with these types of customization scenarios, and you will be confident in using such workarounds without hassle and trial and error. Written by some of the leading experts on UAG, "Mastering Microsoft Forefront UAG 2010 Customization" covers the most complex and challenging options for customizing UAG in a way that is friendly and easy to follow. It walks you through various customization tasks, including explanations and code samples, as well as creative ideas for troubleshooting your work. Until now, only a few of the extensions to UAG's services have been publicly available, and most were only known to a select few. Now, this can include you! Throughout this book, you will tackle how to change the system's look-and-feel, deal with advanced authentication schemes and write special functions that need to be executed as part of the client interaction. With "Mastering Microsoft Forefront UAG 2010 Customization", you too can learn how to customize various aspects of UAG's functionality to enhance your organization or customers' experience.
Publication date:
February 2012
Publisher
Packt
Pages
186
ISBN
9781849685382

 

Chapter 1. Customization Building Blocks

Before we go into discussing the customizations, we need to explore and understand some basic concepts of customization in general, as well as UAG-specific customization technologies and operability. Throughout this chapter, we will also discuss some of the technologies that UAG relies on, such as HTML, JavaScript, ASP, and ASP.NET, so you can judge if your knowledge of these technologies is sufficient or requires further reading. In this chapter, we will discuss the following topics:

  • Introduction to UAG and how it works

  • The UAG detection, login, and authentication flow

  • Customization and supportability

  • The CustomUpdate mechanism

  • HTML, CSS, JavaScript, ASP, and ASP.NET

  • Other web technologies

  • Reading, editing, and debugging ASP code

  • A word about security

  • Further reading

Introduction to UAG and how it works

Ah! Don't worry, we have no intention of boring you with a lesson on reverse proxies — we're sure you've been through that till all your IPs got released. However, you do need to have a clear understanding of UAG and the actual flow of information between various components so you can figure out where best to inject your own stuff.

At the heart of UAG is its main component, the WhlFilter.DLL, which is an ISAPI filter and extension. When you install UAG on a Windows Server, it plugs itself into IIS, meaning that every UAG-related request that passes through this IIS server gets handled by our DLL, and that's when the magic happens. The UAG management console acts as the interface between yourself and the complex backend configurations that get applied when you hit the activation button. Once committed, your configurations are what control how the ISAPI filter behaves in terms of processing requests, headers, content, and the overall security characteristics.

Significant parts of the UAG framework are written using ASP, and these include the UAG login, logout and authentication dialogs, the error-handling mechanism, the endpoint detection, the web-monitor, and more. Then we have the management console itself, which is compiled code. Naturally, UAG has many other components to it, which are less visible to the naked eye.

So where does UAG store its settings and configurations? This can really depend on whether this is a standalone server or an array, but in a standalone deployment the core of the main configurations are stored in two key locations:

  • In a text-based EGF file (stored in<UAG Path>\common\conf\UAG.egf)

  • As a binary vendor parameter in TMG storage (AD LDS)

Other data that is equally important is also held in various XML files within the UAG folder hierarchy, but UAG can be particularly sensitive about it is the two aforementioned data stores. This arrangement still applies in an array configuration but the difference to note here is that the Array Management Server (AMS) will be the one that holds the master configurations for all of the array members. So although each node will have a local copy of the EGF file, they will all rely on the AMS to obtain settings that are common to all members. The configuration stored as part of the array includes custom files that the administrator may create as part of the customization process. Occasionally you might run into certain flags that are stored directly in INC or ASP files, such as the InternalSite site trace flag, which tells UAG to trace the ASP code (more about that at the end of this chapter).

 

Introduction to UAG and how it works


Ah! Don't worry, we have no intention of boring you with a lesson on reverse proxies — we're sure you've been through that till all your IPs got released. However, you do need to have a clear understanding of UAG and the actual flow of information between various components so you can figure out where best to inject your own stuff.

At the heart of UAG is its main component, the WhlFilter.DLL, which is an ISAPI filter and extension. When you install UAG on a Windows Server, it plugs itself into IIS, meaning that every UAG-related request that passes through this IIS server gets handled by our DLL, and that's when the magic happens. The UAG management console acts as the interface between yourself and the complex backend configurations that get applied when you hit the activation button. Once committed, your configurations are what control how the ISAPI filter behaves in terms of processing requests, headers, content, and the overall security characteristics.

Significant parts of the UAG framework are written using ASP, and these include the UAG login, logout and authentication dialogs, the error-handling mechanism, the endpoint detection, the web-monitor, and more. Then we have the management console itself, which is compiled code. Naturally, UAG has many other components to it, which are less visible to the naked eye.

So where does UAG store its settings and configurations? This can really depend on whether this is a standalone server or an array, but in a standalone deployment the core of the main configurations are stored in two key locations:

  • In a text-based EGF file (stored in<UAG Path>\common\conf\UAG.egf)

  • As a binary vendor parameter in TMG storage (AD LDS)

Other data that is equally important is also held in various XML files within the UAG folder hierarchy, but UAG can be particularly sensitive about it is the two aforementioned data stores. This arrangement still applies in an array configuration but the difference to note here is that the Array Management Server (AMS) will be the one that holds the master configurations for all of the array members. So although each node will have a local copy of the EGF file, they will all rely on the AMS to obtain settings that are common to all members. The configuration stored as part of the array includes custom files that the administrator may create as part of the customization process. Occasionally you might run into certain flags that are stored directly in INC or ASP files, such as the InternalSite site trace flag, which tells UAG to trace the ASP code (more about that at the end of this chapter).

 

The UAG detection, login, and authentication flow


When a user types in the URL for a UAG portal, the client computer resolves the URL to an IP address (using DNS or a HOSTS entry, typically, or via his/its defined proxy) and the request is sent to that IP. Then, on the UAG server, TMG receives this client request and cross references this against its firewall policies to ascertain whether the connection should be allowed or denied. If accepted, the request is then sent over to IIS, and in turn to UAG's ISAPI filter for processing.

The ISAPI filter is responsible for an incredible amount of work, some of which can be observed from the output of a UAG trace taken during a client session. What actually goes on during the Client/Server interaction is far too complicated to fully explain here, but at a higher level, a client connects and the filter checks for cookies, essentially looking for one that will identify the user against an existing UAG session. If one is not found then the filter issues a redirect, sending the user to the standard form-based portal login page.

Note

An exception to this is when the request is coming from rich client applications, such as Outlook, ActiveSync, or the various other Office applications, for which authentication can be performed directly (assuming, of course, that the portal has been configured for this method of publishing).

This login page (part of the InternalSite site) forms a part of the core authentication mechanism used by UAG, and to which all trunks rely on for various aspects of access to the portal, such as the endpoint detection and the authentication flow. Creating a new trunk in UAG also creates a new virtual website within IIS with the same name as the trunk. Why would the portal login page be referred to as Internal, even though it's really external? Well that's because historically, when e-Gap was created, the solution actually comprised of two distinct physical servers. Back then, instead of TMG, there was the external server and the internal server. The external server would transfer session data to the internal server, using a hardware-based device that interconnected the two devices, while offering the highest level of data isolation for its generation. The architecture here was clearly of a different nature when compared with UAG, but certain key components were already being used, such as IIS. The key differentiator was that you had two separate instances of IIS, one running on each server. The external one didn't do much work, but the internal one, on the other hand, was where the clever stuff really happened. A lot of that code is still with us today; hence the terminology.

So, in the case of a session cookie not being detected, the browser would be redirected to the login page, but beforehand, UAG will run through its install-and-detect phase, in an attempt to determine whether the client already has the UAG client components installed. Its failure to detect the components would prompt the user with the option to install them or to continue with limited functionality. However, the existence of the components would simply allow UAG's detection routine to initialize and call upon the default detection script (\von\internalsite\detection.vbs), which collects endpoint information and sends it back to UAG using the results function (more about detection is discussed in Chapter 3,Customizing Endpoint Detection and Policies

At this point, an unauthenticated session can be seen in UAG's Web Monitor, and by now UAG has already associated this connection with a unique session ID, represented as a GUID. It's the information that was collected during the detection process that will determine the level of access that the user is granted for any particular session, and the results can be viewed within the Parameters tab as illustrated in the following screenshot:

As you can see in the preceding screenshot, the Lead User and Repository have yet to be populated as the user has not logged in, and this is also represented by X in the Authenticated column.

It's UAG's advanced policy engine that allows for the creation of extremely granular policies that can be enforced across several different levels. Since UAG trunks have their own individual access policies, we have the ability to evaluate a client's request for access based on what was found during detection. A decision can then be made to permit access according to whether or not a client was able to satisfy a given set of configured security policy requirements. One of the collected parameters is the user-agent, which is what a client's browser will send as part of the initial connection process. This string alone is what helps UAG acknowledge the type of endpoint that is connecting, and in turn which of the four core OS policies to apply Windows, Mac, Linux, or Other (which would typically be a phone of some type, or an iPad). Each of these core policies then also have individual subpolicies that are constructed for a specific operating system, so accurate detection of the type of client is a critical part of this deterministic process.

UAG will evaluate policies using the Boolean logic, so as with the preceding screenshot, you can expect to see a TRUE or FALSE against many parameters. In general terms, the majority of the results shown on the Parameters tab are returned from the default detection script previously mentioned. However, custom policies will also show in this list, and how UAG perceives the returned response can be configured in any number of ways. So, you could expect the results of an endpoint policy evaluation ending concluding with FALSE to then redirect a user to the access-denied page.

As part of the login flow, a user will be redirected to the validation page (/InternalSite/Validate.asp), which triggers UAG's authentication mechanism. Depending on the authentication configuration set on the trunk (repository type and settings), UAG contacts the authentication target and validates the user. UAG will also collect additional info, like password expiry and group membership. If the repository is of the Active Directory type, then directory queries using ports 389, 636, 3268, or 3269 will take place, but the actual method used can also change depending on how this is configured. Using the option of querying the DCs directly will instruct UAG to query two explicitly defined domain controllers, whereas using the Forest alternative will enumerate all DCs using Global Catalog services and ports.

Assuming the user's credentials have been accepted, they are then encrypted and stored in UAG's allocated address space, and linked to the authentication repository the user has used, for the duration of that session. If there are applications that have granular authorization settings based on group membership (as opposed to being set to Allow all users on the application's Authorization tab), then UAG will cross check the user's saved domain group membership info against those set for the application to control access and visibility of the application icon within the portal.

At this point, the endpoint policies now come back into play. As with trunks, each application also has its own policies, and these can be used to control which applications will be available to the user. For example, Macintosh and Linux computers do not have all the required endpoint components to support all applications types, so UAG will detect that and prevent access to certain types (RDG-based applications, for example). After the decision process, the user is then redirected to the original URL he initially typed. If that URL is the UAG's root URL, then the redirect would go to the initial application defined on the trunk. This would usually be the Portal itself, or some other application, if so configured by the administrator.

Fetching pages from applications

Once a user has a valid session, he may stare blankly at the screen for a bit, but at some point, he would typically want to launch some application. When the user clicks on an application on the portal, or clicks on a link within an application that is already launched, his browser creates the request and passes it on to UAG. When the filter receives the request, it analyzes the request host header, cookies, and other header information, before trying to determine to which application the request belongs.

UAG may have applications published using the portal hostname method, and others using the application-specific hostname such as with SharePoint. Using the host header included in the request, UAG tries to determine if there are application-specific hostname applications that match that host header, or perhaps the host header matches the trunk's public hostname itself. This, however, isn't foolproof, so UAG has other ways of associating a request to an application, such as looking at the HAT signature itself (more on that later). Another method is to examine the path of the URL, to try and match that against the paths defined within the various applications. There are additional methods, such as the possibility to decide based on the HAT cookie, if such a cookie was received along with the HTTP request, and the Manual URL Rerouting (MUR) rules, which help UAG decide where to send an otherwise unrecognized request. If none of these have helped and a match is not found, then UAG will redirect the user to an error page.

The following screenshots illustrate the differences between these two common types of applications one listing a public hostname and the other has certain paths defined for it:

Once UAG has identified the application the request pertains to, it then initiates the same resource request to the real application server, as defined in the Web Servers tab of the application configuration. This process may involve some adjustment of the host header used in the request, if the target application dictates it (this is common with SharePoint applications).

The request is sent to the backend server anonymously, and if the backend server is configured to accept anonymous requests, it would send back an HTTP status code of 200 OK, and an HTML page with content. This, however, doesn't always work out.

Single Sign On

If the backend server is configured to require authentication, it will typically respond with something other than the page requested. Most commonly, it would return an HTTP status code of 401, also known as unauthorized. This triggers UAG's SSO mechanism, and it will fetch the user's credentials from its memory, where they were stored when the user logged in and resend the same request, with the credentials. Usually, the backend server will accept it, and then reply with the content requested. Occasionally, it may not like the credential set, and again reply with a 401. This could happen if the authentication scheme was not set correctly on UAG.

For example, if the backend application server was configured for Kerberos authentication, the application on UAG needs to be configured for that as well (in addition to other Kerberos Constrained Delegation (KCD)-related trust and delegation particulars). In such situations, UAG retries the authentication a few times, and then gives up and redirects the user to an error page.

Another situation is when the backend application is configured for Forms-Based Authentication (FBA). In this case, the application will deliver back an HTML page with a login form of some sort. UAG has a forms-processing engine, so if a configuration exists for it to identify and work with that form, it will process it and respond with the client's credentials. UAG comes pre-configured to handle some applications' forms out of the box, such as SharePoint, Citrix, and others. An administrator can also create a custom configuration for this, and we will discuss this in Chapter 8, Extending the Login Process with Customization. It's UAG's ability to recognize a form's structure that allows it to inject a user's credentials, while also adding the necessary JavaScript into the page to simulate a user clicking on the Login button. Some forms do not use a generic or conventional way of doing things, so this is where we can extend UAG's functionality to incorporate additional form data that it may not currently be aware of.

The one key dependency that UAG SSO relies on is that both parties, UAG and the target application server, are configured to mutually agree on a common authentication scheme during the challenge response process. Thus, in most cases, this is somewhat as simple to set up as configuring the appropriate authorization type at both ends, and UAG will do the rest. In some scenarios, things can get a little more challenging. This is where we can really capitalize on UAG's flexibility.

Host Address Translation (HAT)

As mentioned, pairing up a client request to an application is critical to UAG's functionality, and the HAT mechanism is a big part of that process for applications that are not using the application-specific mechanism (like SharePoint or Lync publishing). The way it works is by trying to have requests that come from clients bearing a unique signature that will help UAG identify to which application it belongs. To that end, UAG, when it delivers an HTML page to a client, will parse the entire page contents for links and references, and where possible will try to add a unique signature to each of them. The unique signature itself is an alphanumerical hash of the properties of the backend server it pertains to.

As part of this process, UAG places the HTML page into a special buffer in memory and starts parsing it, looking for various HTML and JavaScript elements in the text. For example, it may identify a link to an image that uses the format<IMG SRC="angry.gif" ALT="Angry face" />, and insert the unique signature after SRC, resulting in the tag similar to the following:

<IMG SRCc="/uniquesigf872a75338c81cc6d2bc458e795f24b8/uniquesig0/angry.gif" ALT="Angry face" />

Note

The real signature has been altered to protect the innocent.

After all the changes, the altered HTML is delivered to the client. If all the links and references have been identified and signed, subsequent requests pertaining to this application will all carry the same signature, which in turn allows UAG to easily intercept and handle requests on a per application basis.

Naturally, the process may not always go smoothly. UAG has been designed to handle pretty much every possible HTML tag, as well as common JavaScript structures, but there could always be a miss, and that is something you may need to handle. We will discuss using a custom SRA or Application Wrapper configuration file for this sort of situation in Chapter 4,The Application Wrapper and SRA

 

Customization and supportability


As we said before, a significant part of UAG's code is simple text files containing ASP, HTML, JavaScript, and other code. This means that in theory, you can open any of them with a text editor, and change whatever you want. A brave enough person might even attempt to decompile the UAG filter and mess around with that. However, this is not what this book is about, and the intention is not for you to take drastic measures or rewrite the product yourself. While nothing prevents you from changing any file on your own server, UAG was designed with a specific customization framework, which provides a clean mechanism to perform a supported customization.

What this means is that the team who designed the product intended for you to be able to customize certain files, but also that you should not touch any other files (and if that's not clear, most of the ASP pages have a friendly reminder in them too). We will discuss the technical aspects of this in a minute, but the point here is that whatever you do, you should consider the long-term repercussions of changes you make.

The challenge here is that if you change the files that are unsupported for customization, you run the risk of creating a problem with the code, and in that case, Microsoft's support personnel will not be able to decipher your code changes and work around/through them. Even if you are around to explain, they will most likely outright refuse to touch the server. Naturally, if you are a consultant implementing this customization at a customer's site, an issue might creep up weeks or months later, putting your customer in a tight spot.

Another concern is that UAG's own code may change with a future update, overwriting the changes you made or conflicting with them in a way that causes a problem. For example, with the release of SP1 for UAG, one of the default pages changed in a way that caused many servers who had an improper customization to that page to start showing a 500 error upon entry, which basically bricked those servers until the customization was reversed and redone from scratch. If you are an employee, such a situation could be unpleasant, but if you are an external consultant, this may even put you in a legal bind.

In other words, we strongly recommend you plan your work carefully, sticking with supported customizations, and it wouldn't hurt to also develop a detailed test plan. If the task is a contract, it would be also good to include a support plan as well, in case your code needs updating.

 

The CustomUpdate mechanism


The UAG customization framework is based on a well-known concept often referred to as CustomUpdate. The idea is that some folders within the UAG folder tree contain special folders with this name, and in them you can place your own custom code. When the UAG's code runs, it automatically checks these folders for custom files, and processes them accordingly. For example, here's such a function from the page logo.inc:

As you can see, the command uses the function include Application and defines a filename pattern for when UAG performs its CustomUpdate file check. If the file is found, the function will read its content and process it as if it was a part of the original code (the include function itself is in /InternalSite/Inc/include.inc). The actual filename (logo.inc) is populated into LOGO_INC as part of the file /InternalSite/Inc/IncludeFiles.inc. The following screenshots show these two files:

It's important to keep in mind though, that this processing is sometimes a cumulative processing, and sometimes replaceable processing. Depending on the design of the specific component, UAG might use your file instead of the original file (for example, if you customize the Login page), or in addition to the original file (such as when customizing the endpoint detection script).

The process of customizing a file is simple: you create your file, drop it in the relevant folder, and name it appropriately. The file naming convention used by UAG is:

<trunk Name><Secure><name>.<extension>

The trunk name is obvious. The Secure flag is either 0 or 1, depending if the trunk is HTTP or HTTPS. The name is the original filename, and the extension needs to match.

For example, let's say you want to create a certificate-authentication configuration. We will discuss this more in Chapter 6, Custom Certificate Authentication, but this is also considered to be a customization, as this will almost always require some editing of the ASP code itself to match the organization's certificate scheme. The name of the certificate authentication file is cert.inc, so if your trunk is named Remote, and the trunk is an HTTPS trunk, the file you will need to put in the target folder needs to be named remote1cert.inc.

Note

Letter case is not important in this naming convention.

For the most part, that's about it, and the next user who logs in will reap the benefit of the new custom file (or the error it may generate, if you messed it up!). Adding new files does not impact existing sessions, so if you are testing this yourself, you would need to log out and log in again, and we also recommend clearing your browser cache and cookies as well. Some files will require you to perform a configuration activation to take effect, and some take effect immediately. However, it is important to perform an activation regardless, otherwise, the custom file will not be pushed into the TMG storage and may later miraculously disappear from your server.

Another point worth mentioning is that when customizations are done to a UAG array, they should only be applied to the Array Master Server (AMS). During activation, the custom files will propagate across all array members.

 

HTML, CSS, JavaScript, ASP, and ASP.NET


So how much do you REALLY need to know? Probably not a lot, if you're lucky. Most visual changes only need basic understanding of HTML, and any modern HTML editor should be able to recognize any existing ASP elements and work around them as you change the layout. A lot of benefits can come from adding JavaScript, such as a script to toggle some text on-and-off if a user clicks on Help, or a nice floater to reveal info for your users about how to feed in their domain credentials. ASP, however, is probably the most important thing here.

The ASP web-scripting interface and the VB language it uses are quite old, and a lot of people know them well, so we will not attempt to teach it here. Another key concept is Server-Side Include (SSI), which is also used a lot. Normally, you wouldn't have to change these, but if you need to add your own files, this can become tricky, because inclusions are very sensitive to folder hierarchy. Some parts of UAG were written using ASP.NET, which means you won't be able to edit them, and even reading the code will be quite limited. Cascading Style Sheets (CSS) is also important, as a lot of the look-and-feel of UAG is controlled this way. At the end of the chapter, we have included a list of books that may be a good start towards brushing up on these technologies.

 

Other web technologies


A sensitive topic with UAG is the inclusion of other web technologies, such as Java, Silverlight, and Flash. These are all great technologies which can benefit your code in many ways, but they may not be suitable everywhere. For example, including an Adobe Flash or Microsoft Silverlight animation on the UAG login page may be a terrific visual add-on, but one must keep in mind that UAG's parsing engine won't be able to parse the content, so it may be a bad fit for integration with other parts of the code. You may be able to compensate by hardcoding HAT URLs into your code, but that's a pretty bad practice.

 

Reading, editing, and debugging ASP code


While ASP is not difficult, you may find that the UAG code files may still be a bit challenging to read because every script links to several other files, most of which link to others as well. This means you may often have to hunt through a handful of files to find a certain function and what it does. Some people prefer the use of advanced tools such as Visual Studio, and others are just fine with Notepad, but keep in mind that installing additional software on UAG is not supported. Some stuff is more benign, but be careful not to jeopardize server stability, and if you really feel you MUST install additional stuff, try to at least limit it to non-production servers.

Out of the box, UAG is not set up for easy debugging, but there are a few things you can do to make things work your way. The first step is to enable verbose output of ASP errors, which can be done by executing the following command from an elevated command prompt on a UAG server:

cscript %systemdrive%\inetpub\adminiscripts\adsutil.vbs set w3svc/AspScriptErrorSentToBrowser true

Note

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.

You will then also need to set up the browser on the client to not Show friendly HTTP error messages, so make sure that this box is not selected, as shown in the following screenshot:

If you are debugging a production server, keep in mind that the errors may reveal sensitive info to the end user, so be sure to turn the verbosity back off when finished by running the same script with the keyword FALSE.

Naturally, you can add more output to the ASP code with the response.write method and that's probably the easiest way to know what the server is doing and to isolate issues. In cases where the processing is in the background, or too fast to read, you might be able to use a tool such as HTTPWatch or FIDDLER to record the client-side activity, and then go over the source to find your messages. In case where even this is not suitable or to debug production servers, another tool at your disposal is the TRACE functions that are part of UAG's code.

UAG has a code file named trace.inc, which has several functions that integrate with the ASP code to collect data. To use them, all you have to do is add a line of code into your customization using the following format:

light_trace "what I gotta say"

You will see no visible output, but if you turn on a server trace, the resulting trace will show the text. Naturally, to make it helpful, be sure to put the right data in the trace text. For example:

light_trace "Custom PostPostValidate.inc: Entering function 'Read Lips' at " & now & " for user " & username

Once you have implemented such trace instructions, turn on UAG tracing, with InternalSite tracing, and you should see your messages in the decoded trace data.

For more information, see the following blog post:

http://blogs.technet.com/b/ben/archive/2011/08/08/enhanced-tracing-for-asp-debugging.aspx.

 

A word about security


When working with UAG, and especially when customizing it, one must keep in mind that a UAG server will typically sit on the public Internet, listening for incoming HTTP and HTTPS connections. The product has gone through several development cycles, rigorous testing, and deployments, and is considered to be extremely secure out of the box. However, a single line of bad code could jeopardize the entire server, while potentially leaving your gateway open to risk and compromise.

Talking about writing secure code is beyond the scope of this book, of course, but we strongly recommend that even if you are a seasoned web developer, you should go through secure-coding training, or at least a refresher course. In today's marketplace, your company or customers are usually constantly scanned by one of many hackers and hacking groups, and the risks of customer data exposure or public humiliation are enormous. This means not only being careful about what you create, but also thinking about having a third-party analyze your work, or even perform pen-testing on it. We all want to sleep better at night, don't we?

 

Further reading


We have briefly discussed the technologies used in customizing UAG, and you should strive to understand them to as high a level as possible. The following is a list of recommended books to provide you with a deeper understanding of the topics of ASP, HTML, CSS, JavaScript, Windows Server, Information Security, ISAPI, and COM. None of these are absolutely mandatory, but strongly recommended.

  • Sams Teach Yourself Active Server Pages 3.0 in 21 Days by Scott Mitchell and James Atkinson, ISBN 978-0672318634

  • Head First HTML with CSS & XHTML by Eric T Freeman and Elisabeth Freeman, ISBN 978-0596101978

  • JavaScript: The Definitive Guide by David Flanagan, ISBN 978-0596101992

  • XML in a Nutshell by Elliotte Rusty Harold and W. Scott Means, ISBN 978-0596007645

  • Windows Server 2008 R2 Unleashed by Rand Morimoto, Michael Noel, Omar Droubi, Ross Mistry, ISBN 978-0672330926

  • Hacking Exposed, Web Applications by Joel Scambray, ISBN 978-0071740647

  • Writing Secure Code by Michael Howard and David LeBlanc, ISBN 978-0735617223

  • Essential WinInet: Developing Applications Using the Windows Internet API with RAS, ISAPI, ASP, and COM by Aaron Skonnard, ISBN 978-0201379365

 

Summary


In this chapter, we briefly discussed some of the basic concepts in the world of UAG customization, and reviewed some of the operational principles behind how UAG works as a reverse proxy. We also discussed some additional technologies that come into play when customizing UAG, and suggested some things you might consider studying up on to make the journey easier. In the next chapter, we will deep-dive into the most popular type of customization — the look and feel.

About the Authors
  • Erez Ben-Ari

    Erez Ben-Ari is a long time Technologist and Journalist, and has worked in the Information Technology industry since 1991. During his career, Erez has provided security consulting and analysis services for some of the leading companies and organizations in the world, including Intel, IBM, Amdocs, CA, HP, NDS, Sun Microsystems, Oracle and many others. His work has gained national fame in Israel, and he has been featured in the press regularly. Having joined Microsoft in 2000, Erez worked for many years in Microsofts Development Center in Israel, where Microsofts ISA Server was developed. Being a part of the release of ISA 2000, ISA 2004 and ISA 2006, Erez held several roles, including Operation engineering, Software testing, Web-based software design and testing automation design. Now living in the United States, Erez still works for Microsoft, currently as a senior support escalation engineer for UAG. As a journalist, Erez has been writing since 1995, and has written for some of the leading publications in Israel and in the United States. He has been a member of the Israeli National Press Office since 2001, and his personal blogs are read by thousands of visitors per month.Erez has also written, produced and edited content for TV and Radio, working for Israels TV Channel 2, Ana-Ney communications, Radio Haifa and other venues. Erez is also the author of the hugely successful titles Microsoft Forefront UAG 2010 Administrator's Handbook and Mastering Microsoft Forefront UAG 2010 Customization, also by Packt Publishing. Both titles have received all 5-star reviews on Amazon and are considered to be the most comprehensive guides to UAG in existence.

    Browse publications by this author
  • Rainier Amara

    Rainier Amara is a confirmed IT professional with more than 15 years specialist experience in the field of Internet security and remote access. From a young age Rainier was already renowned for his inquisitive nature and attraction to all things electronic, and by the age of 8 he had already embarked on journey that would feed his passion for IT. It was in his early teens that he received his first personal computer, but his professional career took off at the age of 18, when he served in the French National Army as a communications engineer. From there Rainier has travelled the world in various roles and has not looked back since. Outside of work Rainier spends as much time as he can with his wife and three children doing lots of crazy and wonderful things, and when not being a dad he enjoys downhill mountain biking in the French alps. Who knows what the future holds!

    Browse publications by this author
  • Erez Y Ben

    Erez Ben-Ari is a long time Technologist and Journalist, and has worked in the Information Technology industry since 1991. During his career, Erez has provided security consulting and analysis services for some of the leading companies and organizations in the world, including Intel, IBM, Amdocs, CA, HP, NDS, Sun Microsystems, Oracle and many others. His work has gained national fame in Israel, and he has been featured in the press regularly. Having joined Microsoft in 2000, Erez worked for many years in Microsoft’s Development Center in Israel, where Microsoft’s ISA Server was developed. Being a part of the release of ISA 2000, ISA 2004 and ISA 2006, Erez held several roles, including Operation engineering, Software testing, Web-based software design and testing automation design. Now living in the United States, Erez still works for Microsoft, currently as a senior support escalation engineer for UAG. As a journalist, Erez has been writing since 1995, and has written for some of the leading publications in Israel and in the United States. He has been a member of the Israeli National Press Office since 2001, and his personal blogs are read by thousands of visitors per month.Erez has also written, produced and edited content for TV and Radio, working for Israel’s TV Channel 2, Ana-Ney communications, Radio Haifa and other venues. Erez is also the author of the hugely successful titles “Microsoft Forefront UAG 2010 Administrator's Handbook” and “Mastering Microsoft Forefront UAG 2010 Customization”, also by Packt Publishing. Both titles have received all 5-star reviews on Amazon and are considered to be the most comprehensive guides to UAG in existence.

    Browse publications by this author
Mastering Microsoft Forefront UAG 2010 Customization
Unlock this book and the full library FREE for 7 days
Start now