UAG–Enable SSO by passing user credentials to formular based Web Applications

A lot of Web Applications like Sharepoint or Outlook Web Access make use of formular based user authentication. Some of these applications cannot be configured to use other authentication methods like Basic- or Windows-Authentication. In this case the user has to authenticate twice, one time to login to the portal, the second time, if he wants to start the published application inside the portal. Sharepoint for example can be configured to use the ASP.Net Membership Provider to authenticate external users with forms based authentication. UAG can also be configured to use ASP.Net Membership Provider to authenticate external users like i described in my post here. Both applications use the same repository for authentication and we can use a feature called the Form Authentication Engine built into the UAG product to pass the credentials of the logged in user into the authentication form presented by Sharepoint and do an Autosubmit. Done so, we can bring SSO-Experience to our end-users.

The Mission:

1. Setup an Intranet Sharepoint Site using Windows Authentication
2. Extend the Website to external Users using ASP.Net Membership
3. Publish the extranet Sharepoint Website via the UAG Portal
4. Configure the UAG Formular Engine to work with Sharepoint FBA
5. Test the result

 

1. Setup an Intranet Sharepoint Site using Windows Authentication

---

Start the Sharepoint 2010 Central Administration and select Application Management and click on Manage Web Applications. On the following WebSite click the New button to create a new Web Application.

In the Create New Web Application Wizard select Claims Based Authentication.

Scroll down and check if the Authentication Type for this Web Application is set to Windows Authentication because this Web Application will be used by our internal clients and is not published to any external users.

Change the Application Pool Account to Network-Service and click OK to create the Web Application. I did not make any ohter changes and left the defaults. After the Wizard has finished click OK and select Application Management and click on the Create Site Collections link in the Site Collections section.

In the Create Site Collections Dialog make sure the correct Web Application is selected.

Also fill in a title, select a site template and make sure to add an Active Directory user as Primary Site Collection Administrator.

After the processing has finished you can try to access the Homepage by clickin on the displayed link. The default content shows and you are automatically logged in with your actual credentials.

 

2. Extend the Website to external Users using ASP.Net Membership

---

Navigate back to Application Management –> Manage Web Applications. Select the Web Application created in the steps before and click on the Extend button.

In the Wizard create a new IIS Site, fill in a name and set the port number you like.

In the Claims Authentication Types uncheck Enable Windows Authentication and check Enable Forms Based Authentication. Enter the name of the Membership and Role Providers and change the zone to Extranet at the bottom of the dialog.

After the Web Application is extended you can test the url and you should see a Login Formular

The next step is to configure Sharepoint 2010 to use the ASP.Net Membership SQL Instance for authentication. Because this is beyond the scope here you can use this very detailed Step-By-Step Guide in Donal Conlons Blog.
After setting up Sharepoint 2010 and IIS to use the same ASP.Net Membership provider like UAG we configured both products to use the same authentication repository and you can login to both products with the same usernames and passwords stored in the SQL Database.

 

3. Publish the external Sharepoint Website via the UAG Protal

---

I assume that you have already done the steps provided in my article about UAG and SQL Authentication. So there is a portal up and running and we need to publish a new Web Application through the UAG Management Console.In the UAG Management Console click the Add button to start the Add Application Wizard and click Next on the Welcome Screen.

On the Select Application Screen check the option Web and choose Other Web Application (Portal Hostname).

In the Configure Application Screen type in a name for your application and type in an Application type. Keep the application type in mind because you will need this information later.

In the Select Enpoint Policy Screen select the Enpoint Policies you require. To keep things simple i use the option always for all policy settings. This is not my recommendation but i want to focus on the main solution.

In the Deploying an Application Screen select Configure an Application Server and click next.

In the Web Servers Screen enter the name of your Sharepoint Server, set the Path value to / and enter the Port number your external Sharepoint Site is listening on.

In the Authentication Screen check the Use Single-Sign-On checkbox and add the SQLAuthN Repository as an Authentication Server. Select Both for the Client Authentication Method.

In the Poral Link Screen you can accept the defaults and in the Authorization Screen you can authorize all users to access the application. After that you can exit the Wizard by clicking Finish. Please do not forget to Activate your configuration to store the changes you have made. It will take some time until the new configurations becomes active. Now you can log on to the portal using your SQL Credentials and you can see a new accessable application listed.

When you click on your new application the Sharepoint 2010 FBA login form appears. This is expected and if you enter the same credentials again you should be able to access the Sharepoint content.

 

4. Configure the UAG Formular Engine to work with Sharepoint FBA

---

The next step is customizing some configuration files in UAG to set up the Formular Engine. The Engine has to recognize and to identify the form. The Engine also needs information about the input fields of the form so that the users credentials can be inserted. An Autosubmit script needs to detect the submit button of the form and is fired after the credentials are inserted.

Navigate to the <UAG Installation Folder>\von\Conf\WizardDefaults\FormLogin\ Folder and create a new Folder called CustomUpdate.

Copy the FormLoginCustom.xml File in the CustomUpdate Folder and rename it to FormLogin.xml

Clear the content of the File and insert exactly the same content you can see in the next screenshot. If you have entered a different Application type when you created your portal application then enter the exact Application type you defined. Replace my Application type (SharepointFBA) with your one. Keep in mind that XML-Syntax is case sensitive.

The content identifies your Application type, the URL which presents the form, the supported browser for this form application, the formular name, method and the input types as they appear in the HTML source of the login form. The LoginFormHandler Script checks if there is only one <form>-tag in the HTML source and the SharepointFBA Script is a custom script that identifies the submit-button of the login form and autosubmits the form in JavaScript.

To create a custom Autosubmit script open the file FormLoginDataDefinitions.xml in the <UAG Installation Folder>\von\Conf Folder and mark the complete <SCRIPT>…</SCRIPT> section for the FormLoginSubmitSP14AAM script. Copy the section by pressing STRG-C and insert it after the closing </SCRIPT>-Tag.

After you inserted the copy of the script change the name-attribute value to SharepointFBA and the GetElementByID-String to ctl00_PlaceHolderMain_signInControl_login because this is the ID of the submit-button in the SharepointFBA form.

Open the UAG Management Console and Activate the configuration. Wait some time to let the changes become active.

 

5. Test the Result

From a client computer access your portal url and log in as an external user. Click on the Sharepoint External Access link in the portal and see what happens. You can see the Sharepoint Form for a short while with username and password fields already filled out. After a second or shorter the form is automatically submitted and the user is logged in without any interaction.

Have fun with this nice feature in the UAG product!

UAG – How to Authenticate users against SQL Server

There are certain scenarios where the default authentication providers offered by Forefront UAG do not meet the requirements you have to authenticate your users. One example is the use of SQL Server Authentication which is not implemented in the UAG product by default. One of the most powerful features of UAG and/or IAG is the possibility to extend the authentication mechanisms by defining custom authentication repositories. In this scenario i would like to guide you through the process of how to implement an extranet scenario where you can authenticate extranet users against your Sharepoint 2010 installation using SQL Server as  a custom authentication provider

The Mission:

1. Setting up SQL-Express 2008 SP2
2. Configure the SQL-Express Instance
3. Add a custom authentication provider in UAG configuration
4. Add a custom repository.inc
5. Build a custom authentication function
6. Test the authentication against SQL

So, here we go.

1. Setting up SQL-Express 2008 SP2

---

In my environment i installed UAG in a existing Active Directory Domain. I also installed Sharepoint 2010 on a Windows 2008 R2 Enterprise Server and use SQL-Express as the database for Sharepoint. On this server i installed a second instance of SQL-Express 2008 SP2 for authentication. I will use this instance for claim-based FBA authentication in Sharepoint and i also like to use it as a custom repository in UAG. This is the first step to achieve SSO-Experience for external users.

After the installation of SQL-Express 2008 R2 we need to setup the ASP.Net Membership Database. An easy way to get the database up and running is to use the aspnet_regsql.exe tool. Open a command prompt and navigate to the following directory:
%windir%\Microsoft.NET\Framework64\v2.0.xxxx and start the aspnet_regsql.exe from there.

The Welcome to ASP.Net SQL Server Setup Wizard starts. Click next on the welcome screen. On the next screen select the Configure SQL Server for application services option and click next.

In the Select the server and database page enter your server\instance and the name of the database. If you do not enter a database name the default will be aspnetdb.

You can accept the authetication default values at this time because we will change the SQL-Server authentication mode to mixed mode later on. In the Confirm yout setting Dialog click next and the wizard will setup the database.

2. Configure the SQL-Express Instance

---

Run the SQL Server Configuration Manager tool from the SQL Server 2008 Program Group in your start menu. Enable the Shared Memory, Named Pipes and TCP/IP Protocols for your authentication instance and restart the SQL-Service.

Open the SQL-Server Managment Studio an make sure that the server is configured to allow remote connections. Rightclick on the instance node in the left pane and select properties. Select connections in the left pane and click the checkbox Allow remote connections to this server if it is not already selected.

Th next step is to create a SQL-Login and make this login a dbo for the aspnetdb database. In the left pane of the Management Studio expand the Security node and rightclick Logins. Select New Login…

On the General Page enter a Login name select the SQL Server authentication and enter a password. Clear the Enforce password policy checkbox and select aspnetdb as the default database.

Select the User Mapping page and click the aspnetdb checkbox. In the Database role membership for aspnetdb section select db_owner.

You can now create roles and add users to your aspnetdb. I use a tool called MembershipSeeder which you can download here.

3. Add a custom authentication provider in UAG configuration

---

To follow the next steps i assume that you have successfully configured an HTTPS portal trunk in UAG and you can access the portal with an external client. You should see the default login page like this, if you have configured portal authentication to use Active Directory Forest:

Because we want to give external users a way to authenticate without creating Active Directory Accounts for each of the external users we need to add a new instance of authentication servers to our portal configuration. This is done by clicking on the Configure… button in the Trunk Configuration section within your portal management.

In the Advanced Trunk Configuration Window select the Authentication tab and click Add..

In the Authentication and Authorization Dialog click Add… again

In the Add Authentication Server Dialog select Other as ServerType and type a ServerName like SQLServerAuthN in the ServerName textfield.

Click OK –> Select –> OK to close the dialogs. Activate the configuration changes and keep the ServerName you entered in mind.

4. Add a custom repository.inc

---

UAG is looking for a ServerName.inc file, in this case SQLServerAuthN.inc file, in the <Forefront UAG Installation Directory>\von\InternalSite\inc\CustomUpdate folder. I recommend that you copy the Repository.inc file from the <Forefront UAG Installation Directory>\von\InternalSite\samples to the <Forefront UAG Installation Directory>\von\InternalSite\inc\CustomUpdate and rename it to ServerName.inc in this case SQLServerAuthN.inc

The dependency is that the Servername you entered in the Add Authentication Dialog needs to match the Filename in the CustomUpdate folder. You can open the file with notepad and delete the functions ContinueAuthenticateRepositoryUser and ChangeRepositoryUserPassword because we will not use it at this time. The only functions which should be left in the file are the CheckCredentials, CheckChallange and AuthenticateRepositoryUser functions.

5. Build a custom authentication function

---

In this file we will write a custom function to authenticate users against SQL-Server. As an example you can use the following code:

function AuthenticateRepositoryUser(repository,user_name,password)

    'Preparing Variables
    dim oConn,oRecordset,sCommandText,sConnectionString
   
    'Setting up SQL-Command
    sCommandText="SELECT * FROM aspnet_Users INNER JOIN aspnet_Membership ON aspnet_Users.UserID=aspnet_Membership.UserID WHERE UserName='" & user_name & "' AND Password='" & password & "'"

    'Setting up SQL-Connection-String
    sConnectionString="Provider=SQLOLEDB;Data Source=srvmoss02\AuthN;Initial Catalog=aspnetdb;User ID=FormAuthUser;Password=Pa$$w0rd"

    'Setting up SQL-Connection Object
    set oConn=Server.CreateObject("ADODB.Connection")
    oConn.ConnectionString=sConnectionString

    'Open SQL-Connection
    oConn.Open

    'Send the query to SQL
    set oRecordset=oConn.Execute(sCommandText)
    HEAVY_TRACE "Cannot connect to SQL-Server"

    set authenticate_user_out = GetAuthenticatedUserDetails()
    if TypeName(authenticate_user_out) <> "Nothing" then
        ' User already authenticated by the Filter
        HEAVY_TRACE "Skipping authenticate user again"
        set AuthenticateRepositoryUser = authenticate_user_out
        exit function
    end if

    set authenticate_user_out = Server.CreateObject("UserMgrComLayer.AuthenticateUserOut")

    'Check if the recordset contains rows
    if not oRecordset.EOF then
        'User exists, password is ok
        if oRecordset("Password")=password then
            authenticate_user_out.Success = AUTHENTICATE_SUCCESS
            authenticate_user_out.ErrorCode = 0
            authenticate_user_out.Handle = 0
            authenticate_user_out.Message = ""
            authenticate_user_out.FullUserName = user_name
            set AuthenticateRepositoryUser = authenticate_user_out
        end if
    'Recordset contains no rows
    else
        authenticate_user_out.Success = AUTHENTICATE_FAIL
        authenticate_user_out.ErrorCode = ERROR_CODE_FAILED_TO_AUTHENTICATE
        set AuthenticateRepositoryUser = authenticate_user_out
    end if

end function

Save the file in the location as mentioned above.

6. Test the authentication against SQL

---

Open a browser window on a client and enter the URL to your portal. The Login-Screen appears.

Enter the User Name and Password of a user you created in the aspnetdb. Select the SQLServerAuthN in the authetication dropdown list and click Login.

Now you can access your portal authenticated with SQL-Express.

Let´s double check the success by viewing the session details in UAG Web Monitor.

Well done! Everything is fine now.

Reimage Celestix TMG/UAG Appliance

When working with Celestix Forefront MSA/WSA Appliances you may have to reinstall the Appliance with the default TMG/UAG-Image at some point. It is really easy to reset the Appliance after having followed the various steps as described in the userguide. The image is then reinstalled on the hardware and several actions  will take place to finish the appliance setup thereafter. Some basic initialization tasks take place after the image is copied to the hardware which actually is the core set up of the machine. Some auto-admin-logon tasks start and several vbscripts run during the post installation phase. At this point you might experience a problem that the vbscript does not stop running. The script hangs and nothing more happens. The Appliance fails to reinitialize and all the features, including the typical first-start wizards of TMG/UAG will fail. If you compare the intructions in the Celestix userguide you won´t see any mistakes you may have made. The solution to the problem is that the network interfaces eth0 and eth1 need to have a physical link to run the initialization scripts. There is no documentation about this prerequisit. Hence, you simply need to crossover these two ports or link them to a switch and the reset process will run properly. Celestix has been informed about this documentation issue and I hope they will add this missing information as soon as possible to their Appliance userguide.

Microsoft Forefront UAG Administrators Handbook

A new book is available for peope interested in configuring and administering the Microsoft Forefront UAG 2010. The book is written for Networking and Security Engineers who are intended to integrate UAG in the corporate network. For more information and details click here.

Microsoft Forefront UAG in Common Criteria Evaluation

Microsoft Forefront UAG has formally entered evaluation for Common Criteria Evaluation Assurance Level 2+ with TÜViT as the testing laboratory and is listed in the Evaluated Product List on the BSI website. For more information you can read this blog and you can find the Evaluated Product List here.

How to configure IAG to use ADAM as a custom Repository

Here are the steps for configuring Intelligent Application Gateway (IAG) to use an Active Directory Application Mode (ADAM) instance for user authentication. An how-to on configuring ADAM can be found here in this blog.

All authentication providers IAG uses are defined in a file named RepositoryType.xml. This file can be used as a blueprint for the additional RepositoryType.xml file we create - or you simply use my file as a reference to build your custom repository. In order to get our customizations independent of any updates made to IAG during Servicepack or Hotfix installations we create a folder named CustomUpdate under \Whale-Com\e-Gap\von\conf as you can see in the screenshot:

Then we copy the RepositoryType.xml from the conf folder to the CustomUpdate folder. You can delete all content in the file except the repository for Active Directory or you create a blank RepositoryType.xml and copy in the content of this post. The content of the file for cut and paste can be found here. The following screenshot shows the content in Notepad:

After we created the xml file in the right place we have to commit the configuration changes within the IAG Configuration Application. Make sure the checkbox "Apply changes made to external configuration settings" is checked.



Now we are ready to configure our portal to accept logins from users stored in ADAM. To allow them to log in expand HTTPS Connections and click on you portal. From there click on the Configure button near Advanced Trunk Configuration to open your portals configuration page.

On the Advanced Trunk Configuration Page click the Authentication Tab and click the Add button.

In the Authentication and User/Group Server click Add

In the Add Server Dialog enter the values for your ADAM Instance and the username and password for the user you configured for read access within you adam instance. If you do not want to login with the full dustinguishedName of the user you can fill out the userPrincipalName Attribute of the account. Then the users UPN can be used on the Add Server Dialog and for portal login.

Assuming you have configured your ADAM Instance correctly the Add Server Dialog will close and a new selectable authentication provider is in the list of possible sources on the Authentication and User/Group Server Dialog. Click the Select button and we are nearly at the end of the story.

Now we can create a new application in our portal. In my case i generated a new generic web application pointing to a Sharepoint Site configured to be an extended Site of an existing Intranet Site but located in the Extranet Zone and configured to use forms-based authentication against my Contos Demo ADAM Repository. In ADAM i created a group called Sharepoint. Thus we can security-trim the published Sharepoint Application only to be accessible for members of the Sharepoint Group. To do this, complete the add application wizard and enter the required information there. After completing the wizard edit the created application and select the Authorization Tab of the applications porperty window. Clear the All users are authorized checkbox.

Click the Add button and select the newly created ADAM Repository in the Select Users or Groups Window. Search for the group you created in your ADAM Instance and add the group by clicking the Add button

Click OK twice and activate your configuration. When the configuration activation has finished, you are able to logon to the portal with an account stored in ADAM and you will see the published application if you are a member of the Sharepoint group.

How to set up Active Directory Application Mode (ADAM) for use with IAG

Here are the steps to set up and configure your ADAM Instance to get it working with Microsoft IAG:
First you have to set up the components using Add/Remove Programs - Add/Remove Windows Components - Active Directory Services - Active Directory Application Mode (ADAM)



After the setup has finished you will find a new program group named ADAM under All Programs:

Now you can start creating your instance using the wizard Create ADAM Instance. After the Welcome Screen select Create a Unique Instance:



For the instance name choose any name you like - you can identify your instance after finishing the wizard in services.msc

Define the ports for unencrypted and encrypted LDAP connections. To use encrypted LDAP connections or LDAPS you have to issue a server authentication certificate for the service running your instance

On the next screen you configure the entry point of your LDAP Directory to store individual data. I recommend you to use an entry point like dc=,dc=, for example dc=contoso,dc=local to be able to create OU´s underneath your directory structure

Select a location where you like to store your instance data

Choose a service account under which your instance will run. I prefer to use the network service to achieve a minimum of required permissions

Now you have to select the the ldif-files for schema import. The three ones selected in the screenshot are enough in this scenario

After clicking next two or three times more the creation of your directory will start, the schema files are imported and the service is started. Now you are ready to use your instance.

When the installation is finished you can find the ADSI-ADAM-Editor Tool within the ADAM Program Group created during the installation. You are using this tool to create users, groups, ou´s and to fill out the properties you need. The first thing that needs to be done is to establish a connection to your fresh installed LDAP Directory. Therefore you create your connection like the screenshot shows by right clicking the top node and select connection:

When you are connected you are able to create an ou by right clicking your LDAP structure and selecting New --> Object and click organizationalUnit. In the following dialog enter the name of your ou and click finish. This procedure may look something like this:

In the same way you can create user accounts in your ou. Right click the ou and select New --> Object --> user. Fill in the name for example Demo User, click next and finish. The user object is created but disabled. The account policies for the server you are running ADAM on need to be achieved. After you set a password in compliance with your password policies you can enable the user account. To set the password you just need to right click the user object and select Reset Password. To enable the user right click the user object and select properties and search for the attribute named msDS-UserAccountDisabled. Doubleclick the property and set the value to false.

The next step is to enable read access on the directory for your created user. In ADSI-ADAM you can see a node called CN=Roles. You can find three predefined groups named Administrators, Readers and Users. To give read access to our created user we need to right click the group named readers and select the property member. Click edit to open the membership window for that group. Enter the full distinguishedName of the user object you like to put in.



ADAM by default is configured to only allow secure connections. For interaction with IAG authentication we connect to the ADAM instance using the simple bind method. You should think about securing this communication, that means encrypting using IPSec. To test that simple bind will NOT work out-of-the-box you can use ldp.exe which can be startet through the ADAM Command Prompt in the ADAM Program Group. As you can see unencrypted authentication is disabled by default.



Mind the message about simple bind in the lower end of the ldp tool. To enable simple bind you have to use the ADAM Command Console using the dsmgmt command. Very simmilar to ntdsutil you configure the ds behavior to allow password operations on unsecure connections. The following screen shows you the exact commands in dsmgmt.



After configuring the ADAM instance you are able to bind to the directory using simple bind.



Everything is done so far. You can additionally create a group, for example Sharepoint in the same way you created a user or an ou. In the value for the group-type enter 2147483650. Adding users to the group can be done in the same way you added the demo user to the Readers group for ADAM instance reader access. Select the member attribute of the group an add the user using the distinguishedName of the user object. We can continue with our work in IAG now.