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.