Unified Identity for Web Apps – the easy way

It makes sense, when developing Azure applications, to offer better security than the traditional ID & password. It is better to allow customers to use some of their existing online identities such as Microsoft Live ID, Google, Yahoo or Facebook. Security tokens provide a neat way of doing this.

In this article we’re going to take a look at how to protect a web application via security tokens.  We already know how to configure a Windows Azure Active Directory Access Control (WAADAC, formerly known as Windows Azure Access Control Service, or just ACS), so now we’ll go through the steps involved when setting up security tokens.

There are few key points you have to look after in order be happy with the results and eliminate most of the rookie mistakes. Before we begin, here’s the WAADAC demo code if you just want to play around with it. Let’s create our first web application and prepare it for token/claims authentication. In order to successfully run the solution (and complete the code if you decide to do it yourself) you need to have Windows Identity Foundation (WIF) SDK installed on your computer. Open Visual Studio and create a new ASP.NET Web Application. For the demo, my app is named “WaadacDemo”. The tool that comes with the SDK (Federation Utility tool) plugs the required modules within the <system.webServer> section of our web.config file. This section is only recognizable by IIS 7.0+ and/or IIS Express.

The first thing we need to do is to set up our web application to work with IIS Express (or local IIS) instead of using ASP.NET Development server (a.k.a. Cassini), which does not recognize and respect the <system.webServer> section. While setting this option, I also chose a specific port for our application just to make sure it runs on the same port every time. All these settings are managed in the “Web” tab under the “Properties” window of the Windows Azure Web Application project:

We’ll write in some of the application settings so that we can go and register it as a Relying Party Application (or just RP) in our ACS namespace:

  • Application realm: http://localhost:2700/
  • Return Url: http://localhost:2700/

Now, create a namespace and register the application with it. You can read more on how to do this in my previous article “Online identity management via Windows Azure Access Control Service”. Add Live ID, Yahoo, and Google as Identity Providers and create the default pass-through rules for all the IdPs registered with the application. Now get the federation metadata URL from your ACS Management portal and copy it:

Now we add the Windows Azure Active Directory Access Control STS (Security Token Service) as an STS reference to our web application. Fortunately for us, it’s fairly easy to accomplish when we have WIF SDK installed. Just right-click on the Web Application project and select the “Add STS reference” menu item:


Follow the wizard which will ask couple of trivial questions like the location of the web.config file to be edited to inject token processing modules, and the application URI. The former is automatically filled out, while you need to enter there the URI of your application (http://localhost:2700/ as configured earlier) in the latter. When you click “next” an error message (ID1007) will pop up asking you whether you want to continue with securing an application which is not on HTTPS protocol – which is fine for our demo purposes.


The next screen will ask us to provide details about the STS (Security Token Service) we want to rely on. Here you need to choose the “Use an existing STS” option to make use of Windows Azure ACS. Paste the Federation Metadata URL that you took from your Access Control Service (you can find it under “Application Integration” menu on the left) and click “Next”.


Next, we’re asked about encrypting the security token. Let’s leave it unencrypted for now (which is the default). Then we come to a window with offered claims by the STS, just click “Next”. The final window is a summary of all tasks that will be performed in order for our application to leverage Claims authentication. Click “Finish” and now you have a Claims ready application!

Make sure you don’t rush testing. An ASP.NET validation error will be triggered when you successfully get the security token from ACS and try to present it to the Web Application. Why is that? Remember what a security token is? It’s simply an XML structured data. Digitally signed XML data, which is being POST-ed to your “Return URL”. And the default ASP.NET validation does not like it! How do you avoid that? The default error message suggests that we set <httpRuntime requestValidationMode="2.0" /> at web.config file, under <system.web> and disable request validation for the particular page (usually default.aspx). This would, however, kill your application’s security, exposing your return URL to a potential attacks, so you don’t want to do that.

There is another way to avoid validation error messages. You could use Microsoft’s provided CustomReqeustValidator (found in almost any lab) which is part of the Identity Training Kit. You need to set it up in httpRuntime again, but this way it would be <httpRuntime requestValidationType="MyCustomRequestValidator, MyAssembly" />. Much better than turning off validation.

There is, however a third and less known approach, which I find particularly interesting, suggested in Erik Brandstadmoen’s blog. He suggests that you configure the Return URL to a “black hole”, which is essentially a non-existing resource, and disable the request validation for that resource. You are safe to do that in terms of switching off request validation, as these requests will not execute any of your application’s pages/handlers. So, now we have slightly different web.config, with an additional location element:

Slightly modified WIF (wsfederation) section:

Don’t forget, however that you must match the “reply” parameter of wsFederation element with the “Return URL” parameter of your Relying Party configuration in the Access Control Service.

A final step that I suggest you explore is to play with the rules. In the provided code sample I have included an /Admin section of the site. It is protected with the standard ASP.NET role protection mechanism:

I’ve also included menu item to link to this location. When you run the app, you will not be able to access that part of it. In order to access it, you need to add a particular Claims Transformation rule in the ACS. Go to the ACS management portal, navigate to the Rule Groups, select the rule group which you created for your app and click “Add” to add new rule:


Save this new rule.

Try to run your application now! You will be automatically redirected to the ACS login page, where you can chose which IdP to use. Authenticate with either Yahoo or Google and your application will get a Name claim and an EmailAddress claim, along with Nameidentifier and IdentityProvider claims. If you use Live ID to sign in, your application will only get a NameIdentifier claim and IdentityProvider claim (you can read more on that claims issues in my posts on the basics of Claims and on online identity management. If you login with the configured Gmail account, you will also be able to navigate to the /Admin section of the site.

And finally, you may ask – why does the “Sign Out” link in my code work, while the Sign Out link for the application you just created doesn’t’? Well, I edited the master page (Site.Master) and replaced the default “LoginStatus” control with WIF provided “FederatedPassiveSignInStatus”, which will do the work for you.