Mittwoch, 31. August 2011

UAG–How to access Remote Desktop Web Access using SSO

UAG offers a a very smart way to integrate Remote Desktop RemoteApps into the UAG portal. For different reasons many customers want to publish the Remote Desktop Web Access Application for their portal users as a link in the portal home. However, the Remote Desktop Web Application uses forms-based authentication by default, that means the UAG logon credentials need to be delegated to the RDWeb Application using the Formular Engine delivered by UAG. In this post i like to describe the steps needed to publish RDWeb Acces into the UAG portal and provide single-sign-on to the RDWeb Application using the formular engine. There is a solution to configure RDWeb App to use Windows Integrated Authentication and to delegate Kerberos/NTLM credentials to the RDWeb App, but this is not part of this post at the moment.

The Mission:

1. Setting up RDWebApp to work with UAG
2. Publish RDWebApp as an Other Web Application in UAG portal
3. Analyze the RDWeb App Login Form
4. Configure the UAG Formular Engine
5. See SSO working with RDWebApp

So, let´s rock now!

1. Setting up RDWebApp to work with UAG

In my scenario, i installed a Windows Server 2008 R2 and assigned the roles Remote Desktop Session Host and Remote Desktop Web Acces on a single virtual box. After assigning the Remote Desktop Role and installing the Remote Desktop Web Application Role-Service you can notice, that RDWebApp is using a self signed certificate to use SSL encryption when you access the RDWebbApp Website. This leads to a certificate error displayed in the browser window if you try to access the RDWebApp.


So we need to swap the self signed certificate to a trusted certificate issued by a trusted certifiaction authority. For internal resources i used an Active Directory integrated certification authority and i requested a Webserver certificate from there. Keep in mind, that the common name of the certificate needs to match the servername you type into the publishing wizard in UAG! For example, if you use an address like the common name of the certificate needs to be The certification authority issued the certificate needs to be trusted (which is automatically done, if you use an AD integrated CA) as a Trusted Root Certification Authority in the UAG certificate store. If you have difficulties in dealing with certificates, feel free to drop some lines in the comments section beyond this article and i will post a more detailed description in how to setup this.


If you request the RDWebApp from an internal Computer there should be no warings and the website should look like this:


As you can see no certificate warining is displayed anymore.

2. Publish RDWebApp as an Other Web Application in UAG portal

Open the UAG Management Console and click the Add button beyond the Applications section. Select Next to bypass the welcome message. In the Select Application Dialog change the default to Web and select the Other Web Application (portal hostname) template.


Click Next. In the Application Name Textbox enter a name for the published Application like Remote Desktop Website and enter an Application Type for example RDWEB. We will need the Application Type in later steps and it is used in XML-Files. Remember that XML is case-sensitive so keep the spelling of your Application Type in mind.


Click Next. In the Select Endpoint Policies Dialog change the Access Policy to Always. This is done for testing purposes only and i do not recommend you to use this as an option in your production environment.


Click Next. In the Deploy an Application Dialog select Configure an Application Server because we are using a single webserver. In the Web Servers Dialog select the IP/Host-Option and enter the servername into the Adresses list. The servername entered here needs to match the common name of the webserver certificate that is used by IIS on the Remote Desktop Web Access Website. In the Paths list enter the url path to the Remote Desktop Web Access website. By default this is /RDweb/*. Keep the defaults for HTTP and HTTPS Ports.


Click Next. In the Authentication Dialog enable the Use SSO checkbox and select your authentication source. In my case i configured my Domain Controller as an authentication source for portal and application access. As the Remote Desktop Web Access Website uses HTML-Form authentication select the HTML-Form option to delegate the user credentials.


Click Next. In the Portal Link Dialog click next. In the Authorization Dialog click next. Click Finish to close the Wizard. In the UAG Management Console click the gear icon to activate your configuration. From a client PC logon to the portal an notice, that the Remote Desktop Web Access Website is visible as a new application in your portal.


If you hit the link your browser is redirected to the login page of the Remote Desktop Web Access website.


3. Analyzing the RDWeb App Login Form

With the login form opend in the browser we can do some visual analysis about the content of the form. There are two textboxes, one for the userdomain\username and one for the password. Further there is a submit button to send the form. To identify the form elements we need to view the source code of the page. Right-click the form in the browser and select View source to open the source code view. We need to extract some more details to identify each element we need to create a custom form login. That UAG can identify the login page we need the name of the form and the method used to submit the data to the webserver. This information can be found in the <form>-Tag in the source code.


As we can see the name and id of the form is: FrmLogin and the method is: post. Now we need to identify the Textbox-Elements so we can search the source code for “type=text”. We need the id-Element of the User-Textbox and the id-Element of the Password-Textbox.


Once we have found the Username and Password textboxes in the source code we can see that the Username-Textbox-ID=DomainUserName and the Password-Textbox-ID=UserPass. Now we need to identify the submit button so let´s search for an type=submit in the source code.


The id is: btnSignIn. Now we have gathered all information we need to configure the Fromular-Enging in UAG.


4. Configure the UAG Formular Engine

Locate the folder  \von\Conf\WizardDefaults\FormLogin in your UAG installation path. If there is not already a folder named CustomUpdate create the folder and copy the file FormLoginCustom.xml to the CustomUpdate folder. Rename the file to FormLogin.xml inside the CustomUpdate folder. The structure should look like this:


Open the file and remove all content. Edit the file and enter the xml-Code so that it exactly looks like this:


Or simply cut and paste the content from here:

<!-- app_id added by configurator, dont edit -->
<USAGE description="form_login">
<SCRIPT_NAME source="data_definition">FormLoginSubmitStandard</SCRIPT_NAME>
<AGENT_TYPE search="group">all_supported</AGENT_TYPE>
<SCRIPT_NAME source="data_definition">FormLoginHandler</SCRIPT_NAME>
<!-- one of NAME or ID could be used. Value could be blank if no form search required -->
<CONTROL handling="dummy_value">
<CONTROL handling="dummy_value">

As you can see, the information we gathered about the form is used to identify the form itself, the method , the textbox-controls and variables like sitedomain\siteusr and sitepass are used to fill in the values with the credentials of the logged in user. Keep in mind that xml is case sensitive. The <NAME>-Elements must match the form-elements exactly! Save the FromLogin.xml file and in UAG Management Console activate your configuration.

5. See SSO working with RDWebApp

Login to your Portal and click the Remote Desktop Web App link. You can see the RDWebApp Login Form by a fraction of second filled with dummy values. Then the form is automatically submitted an you are redirected to the Remote Desktop Website without using your credentials again.


SSO to RDWebApp is done now. Enjoy!