Example XMLHTML code for UAG AppWrap process to provide a “Cover-up” page for Custom Form Login SSO.

Article
08/07/2012

Hello Everyone! We’ve seen a lot of requests in the past regarding examples on how to create” cover-up” pages utilizing the AppWrap process. I thought I would take a moment to put an example of HTML code for a basic AppWrap out there.

*Please do keep in mind that this information is only an example and will need to be adjusted and tested in every given scenario. There are many ways to accomplish this process. This blog was created to start you on your way in a thought process to complete your desired needs.

So what do I mean by “cover-up” pages? Well, think about the possibility of using the Form Fill process that UAG offers. This process is used when you are utilizing Forms Based Authentication on backend applications (such as SharePoint) and you don’t want your clients to have to provide credentials multiple times. You can have UAG fill in the credentials that were used to authenticate to UAG.

* For more on the Form Fill process please refer to the following articles:

https://blogs.technet.com/b/ben/archive/2010/09/02/uag-custom-form-login.aspx

https://blogs.technet.com/b/ben/archive/2010/01/23/custom-form-login-sso-how-to.aspx

All that said, still… what do I mean by “Cover-up” pages and why do we need them? Well, when you use the Custom Form Login process the client hits the back-end application server through UAG and gets posed with a Form Based Authentication page. UAG can then fill in that Form for the client a moment later giving a Single Sign-on (SSO) type of experience. The problem is that the user may “see” the Custom Form Login process taking place. They may see the backend servers’ Form Based login page appear; and then see the form automatically populated and submitted (by UAG). This may be a less than ideal experience for the user and could potentially cause some confusion. Therein… the “Cover-up” page! The “Cover-up” page simply “hides” the Custom Form Login process from the user. It will use the AppWrap process to tell UAG “When you see this specific application send a Form Based Authentication page to the client, replace it with a different page so the client doesn’t even see the Form.” The example I give below is nothing more than a white square that covers up the entire FBA page.

NOTE: Please know that for this example to work as expected, you should have already successfully configured the Custom Form Login process. If you haven’t, your clients will never see the Forms Based Authentication page and time out!

AppWrap explanation:

AppWrap (Application Wrappers) are customization files that enable UAG to search for specific types of HTTP Responses from back-end application servers and manipulate them. This UAG customization feature gives you a way to provide the external client with edited content that will provide them a better overall browsing experience.

*For more on configuring AppWraps please refer to the following Blogs:

https://blogs.technet.com/b/ben/archive/2011/05/12/appwrap-and-sra.aspx

https://blogs.technet.com/b/edgeaccessblog/archive/2009/11/17/appwrap-in-uag-what-s-new.aspx

In my example for a “Cover-up” page we need to have the AppWrap look for the Login page by both the application type, and the URL pattern. We then replace the HEAD of the page with added elements to create a white “Cover-up” square.

HTML Explanation:

We want to cover the entire screen, so we create an HTML element ("DIV", which stands or 'document divisions') that has no contents, and we set it to cover the screen. To do so, we create a style-sheet element called 'cover', and assign it to the blank DIV using the id attribute

The style element itself is supposed to cover the entire screen with a white curtain, so we set it to have the following elements:

1) Color: white

2) Location: starts at the top-left corner of the screen

3) Size: cover 100% of the screen

This looks like this:

<style>

#cover {

background-color: #ffffff;

position: absolute;

top: 0;

left: 0;

width: 100%;

height: 100%;

}

</Style>

The 'absolute' position attribute means that the position where it starts is not relative to where this DIV is located in the HTML, but absolute...starts at the very top and left position of 0.

In HTML, the line break has no meaning, so to make it easy for AppWrap, we simply remove those, and compress it all into one line that has both the STYLE tag and the DIV tag:

Final AppWrap (Base64 encoded):

* In the example below you will notice the sections <APPLICATION_TYPE> and <URL>. The information in these tags will be populated with the specific values from your environment.

 <APP_WRAP ver="3.0" id=" WhlFiltAppWrap_HTTPS.xml">

<MANIPULATION>

    <MANIPULATION_PER_APPLICATION>

        <APPLICATION_TYPE>Application_Type_Description</APPLICATION_TYPE>

            <DATA_CHANGE>

                <URL>.*login\.asp.*</URL>

                    <SAR>

                        <SEARCH encoding="base64">PEhFQUQ+</SEARCH>

                        <REPLACE encoding="base64">PEhFQUQ+PHN0eWxlPiNjb3ZlciB7IGJhY2tncm91bmQtY29sb3I6ICNmZmZmZmY7IHBvc2l0aW9uOiBhYnNvbHV0ZTsgdG9wOiAwOyBsZWZ0OiAwOyB3aWR0aDogMTAwJTsgaGVpZ2h0OiAxMDAlO308L1N0eWxlPjxkaXYgaWQ9ImNvdmVyIj48L2Rpdj4=</REPLACE>

                    </SAR>

                    <SAR>

                        <SEARCH encoding="base64">PGhlYWQ+</SEARCH>

                        <REPLACE encoding="base64">PEhFQUQ+PHN0eWxlPiNjb3ZlciB7IGJhY2tncm91bmQtY29sb3I6ICNmZmZmZmY7IHBvc2l0aW9uOiBhYnNvbHV0ZTsgdG9wOiAwOyBsZWZ0OiAwOyB3aWR0aDogMTAwJTsgaGVpZ2h0OiAxMDAlO308L1N0eWxlPjxkaXYgaWQ9ImNvdmVyIj48L2Rpdj4=</REPLACE>

                    </SAR>

            </DATA_CHANGE>

    </MANIPULATION_PER_APPLICATION>

</MANIPULATION>

</APP_WRAP>

Final AppWrap (plain text):

* This plain text version is just an example of the “Decoded” version of the AppWrap to make it a little more understandable. Please note: You MUST use the Base64 Encoded version above.

 <APP_WRAP ver="3.0" id=" WhlFiltAppWrap_HTTPS.xml">

<MANIPULATION>

    <MANIPULATION_PER_APPLICATION>

        <APPLICATION_TYPE> Application_Type_Description </APPLICATION_TYPE>

            <DATA_CHANGE>

                <URL>.*login\.asp.*</URL>

                    <SAR>

                        <SEARCH><HEAD></SEARCH>

                        <REPLACE><HEAD><style>#cover { background-color: #ffffff; position: absolute; top: 0; left: 0; width: 100%; height: 100%;}</Style><div id="cover"></div></REPLACE>

                    </SAR>

                    <SAR>

                        <SEARCH><head></SEARCH>

                        <REPLACE><HEAD><style>#cover { background-color: #ffffff; position: absolute; top: 0; left: 0; width: 100%; height: 100%;}</Style><div id="cover"></div></REPLACE>

                    </SAR>

            </DATA_CHANGE>

   </MANIPULATION_PER_APPLICATION>

</MANIPULATION>

</APP_WRAP>

I hope the information I provided above helps out! Make sure to check out all the links I provided to the additional Blogs as they will get you a long way in your customization processes!

Author

Brett Crane - Sr Security Support Escalation Engineer, Microsoft CSS Forefront Security Edge Team

Reviewer

Richard Barker - Sr Security Support Escalation Engineer, Microsoft CSS Forefront Security Edge Team

Example XMLHTML code for UAG AppWrap process to provide a “Cover-up” page for Custom Form Login SSO.

Additional resources