Windows Identity Foundation (WIF) By Example Part II – How To Migrate Existing ASP.NET Web Application To Claims Aware
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:
<body>
<form id="form1" runat="server">
<asp:Literal ID="UserID" runat="server"></asp:Literal>
</form>
</body>
- 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:
<authentication mode="Windows"/>
- 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:
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 https://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:
- Click save. Then click green Start button, it should turn red.
- 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:
- Click Next. You should be presented with warning similar to the following:
- 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.
- 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.
<httpRuntime requestValidationMode="2.0"/>
<pages validateRequest="false"/>
- 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:
- Congratulations! Your application is Claims Aware and protected by Windows Identity Foundation.
More Info
- Windows Identity Foundation (WIF) By Example Part I – How To Get Started.
- Identity Developer Training Kit
- A Guide to Claims-Based Identity and Access Control – Code Samples
- A Guide to Claims-Based Identity and Access Control — Book Download