September, 2010

In this post I outline the steps I needed to complete in order to migrate ASP.NET site from using Windows Integrated authentication to using Windows Identity Foundation.

Summary of steps:

Step 1 – Create simple ASP.NET application
Step 2 – Configure and test the application for Windows Integrated authentication
Step 3 – Review prerequisites for using Windows Identity Foundation (WIF)
Step 4 – Download and run SelfSTS
Step 5 – Secure ASP.NET application With Windows Identity Foundation
Step 6 – Consume Claims in code and test your work

The rest of the post is detailed explanation for each step followed by resources in the end.

Step 1 – Create simple ASP.NET application

Run Visual Studio under administrative privileges. It’s not required for this step but it will be required when using Windows Identity Foundation.
From the menu choose New Project and then point to ASP.NET Empty Web Application. Give it a name, for example, MigrateWindowsAuthentiactionToWIF. Click OK.
In Solution Explorer right click on the MigrateWindowsAuthentiactionToWIF solution and add new Web Form, give it a name, for example, Default.aspx.
Drag Literal User Control from the Toolbox and place it between <form> tags in Default.aspx. Give it a name, for example, UserID. The markup should look similar to this:

Switch to Default.aspx.cs - the code behind of Default.aspx – and add the code that identifies current user and prints it out to the Literal User Control, the code should look similar to this:

protected void Page_Load(object sender, EventArgs e)
{
UserID.Text = User.Identity.Name;
}

Compile the application to make sure there are no compilation errors.

Step 2 – Configure and test the application for Windows Integrated authentication

Open web.config file and make sure that the application requires Windows Integrated authentication, the configuration should look similar to the following:

Test your application by right clicking on the Default.aspx page in Solution Explorer and choosing View in Browser option. You should see the page displaying your user name in format similar to domain\username or computer\username. Here is what I have got:

Windows Integrated Authentication ASP.NET

In the previous steps I have created an ASP.NET web application that utilizes Windows Integrated Authentication.

In the next section I will accomplish steps to migrate my ASP.NET web application to using Windows Identity Foundation for authentication.

Step 3 – Review prerequisites for using Windows Identity Foundation (WIF)

There are several prerequisite in order to work with Windows Identity Foundation. Short list is as follows:

Install WIF runtime that suits your OS.
Install WIF SDK.

More info here Windows Identity Foundation (WIF) By Example Part I – How To Get Started.

Step 4 – Download and run SelfSTS

To make ASP.NET application Claims Aware there is a need for STS (Security Token Service). Download and use SelfSTS utility that emulates minimal behavior of STS. It’s available here http://code.msdn.microsoft.com/SelfSTS.

NOTE. SelfSTS utility is for development and testing purposes only. It’s insecure in any possible way. Do not use it for production purposes.

Download and run the utility. No installation needed. It’s simple exe. Optionally, click on Edit Claims Types and Values and provide your own. Here is how mine looks:

Claims and Values in SelfSTS

Click save. Then click green Start button, it should turn red.

SelfSTS for WIF

Copy the URL in Metadata textbox – it’s needed when converting the ASP.NET application to claims aware which is next step.

Step 5 – Secure ASP.NET application With Windows Identity Foundation

Switch back to Visual Studio.
In Solution Explorer right click on the solution and click on Add STS Reference... option.
Type the URL to your ASP.NET application in Application URI text box, here is mine:

FedUtil Application URI

Click Next. You should be presented with warning similar to the following:

WIF - insecure connection

Click Yes to continue. NOTE, this exercise is for development and testing purposes only. For production purposes always use HTTPS.
On Security Token Service page of the wizard chose Use an existing STS option and paste the URL to metadata exposed by SelfSTS to STS WS-Federation metadata document location textbox similar as depicted below, click Next.

SelfSTS metadata in FedUtil

You should be presented with a warning that security endpoint exposed over insecure connection. Click Yes to continue. NOTE, exposing the end point over insecure connection is suitable only for development and test purposes, but never for production.

Click Next [Disable certificate chain validation option] on STS signing certificate chain validation error page of the wizard. Another insecure option suitable only for development.
Click Next [No Encryption option] on Security Token encryption page of the wizard. One more insecure option.
Click Next on Offered claims page of the wizard.
Click Finish on Summary page of the wizard. You should be presented with a dialog “Federation Utility completed successfully”. Click OK.
Review the structure of the solution – FederationMetadata folder was added.
Review web.config – multiple entries were added. Notice that authentication mode is set to None in web.config. It is interesting to note that authorization section set to deny unauthenticated users. Oxymoron? ;)

Step 6 – Consume Claims in code and test your work

Add reference to Microsoft.IdentityModel.
Add using Microsoft.IdentityModel.Claims; declaration.
Open Default.aspx.cs and add the code that consumes claims populated in the application context and specifically in User variable, similar to the following:

IClaimsPrincipal claimsPrincipal = Page.User as IClaimsPrincipal;
IClaimsIdentity claimsIdentity = (IClaimsIdentity)claimsPrincipal.Identity;
foreach (var claim in claimsIdentity.Claims )
{
Response.Write(claim.ClaimType + " = " + claim.Value + "<BR/>");
}

Compile your application and browse to the Default.aspx page. You should receive the following exception:

Open web.config and loosen the security by adding the following entries inside system.web node. validateRequest is by no means the ultimate security feature, it’s been known for several weaknesses. So even when it’s on, thorough input validation must be performed. Turning it off lowers security bar. Be aware of it. In production this must be addressed.

Try navigating to Default.aspx.cs again. The result should be similar to the following (except the values would be different), here is how mine looks:

ASP.NET application protected by WIF

Congratulations! Your application is Claims Aware and protected by Windows Identity Foundation.