The First Few Steps to Building a Claims Based Application

If you’ve been through my earlier blog “An Introduction to the world of claims” you are now familiar with the most frequently used terms in the “Identity world”.

Next lets take a generic walkthrough of the basic steps you will go through when you make a Claims Aware/Claims Based/Relying party application

Step 1:-  You will make you application Claims Aware

The Windows Identity Foundation (WIF) provides a common programming model for claims that can be used by both Windows Communication Foundation (WCF) and ASP.NET applications. You need to add the Microsoft.IdentityModel.dll as a reference dll which gives you another property called Identity.Claims.

Making your application Claims aware involves a couple of steps at the config level(we won’t get into details right now) but the good news is that your core code does not get changed. Most probably your code is of the form

protected void Page_Load(object sender, EventArgs e)
    var user = (User)Session["LoggedUser"];
    var repository = new TimeSheetRepository();
    var expenses = repository.GetTimesheets(user.Id);
    this.MyTimesheetsGrid.DataSource = expenses;

Even after making your application claims aware this code remains unchanged. What changes is an addition to your Global.aspx which reads the claims delivered by the STS and creates the Session User out of it.

So you will have something like this in your Global.asax file

protected void Session_Start(object sender, EventArgs e)
    if (this.Context.User.Identity.IsAuthenticated)
        string issuer =
        string givenName =
        string surname =
        string costCenter =
        var repository = new UserRepository();
        string federatedUsername =
        GetFederatedUserName(issuer, identity.Name);
        var user = repository.GetUser(federatedUsername);
        user.CostCenter = costCenter;
        user.FullName = givenName + " " + surname;
        this.Context.Session["LoggedUser"] = user;

Don’t focus on the code details yet. The point to be taken home is that your code did not change. You just had to make some changes in your web.config, added a handler in your Global.asax and your app is ready


Step2:- Decide on your Issuer(STS)

You accept claims from “Issuers” you trust. Examples of standard off the shelf issuers are ADFS, LiveID, Kerberos etc. Based on your requirement you may end up using one of these ready made issuers or maybe as an application developer with custom authentication requirements you may be asked to make an issuer. Even if its the latter case, there are sample issuer templates(ASP.NET Security Token Service and WCF Security Token Service) provided in VS2010 to allow you to make Custom Issuers and lot of guidance on how to configure them so don’t worry about it.


Templates in VS2010 Create new Website!

Step 3:- Make your application “Trust” the issuer.

Like i said earlier,your application needs to trust the token issuer , only then should it accept a claim it received. When you configure an application to rely on a specific issuer, you are establishing a trust (or trust relationship) with that issuer.
There are several important things to know about an issuer when you establish trust with it:
• What claims does the issuer offer?
• What key should the application use to validate signatures on
the issued tokens?
• What URL must users access in order to request a token
from the issuer?

Just like in a Web Service information about the service can be read from a WSDL, in this case you get all your answers by asking for a FederationMetadata document. This is an XML document that the issuer provides to the application. It includes a serialized copy of the issuer’s certificate that provides your application with the correct public key to verify incoming tokens. It also includes a list of claims the issuer offers, the URL where users can go to get a token, and other more technical details, such as the token formats that it knows about

VS2010 makes trusting an issuer easy by providing an “Add Service reference kind of experience” for adding an Issuer..

Right Click on your application and select “Add STS Reference” to start the configuration wizard..More details on how to populate the wizard in another post..Point to be taken home :- its easy to add a trusted issuer!


Step4:- Configure your STS to know about the application!!

The issuer needs to know a few things about an application before it can issue it any tokens:
• What Uniform Resource Identifier (URI) identifies this application?
• Of the claims that the issuer offers, which ones does this application require and which are optional?
• Should the issuer encrypt the tokens? If so, what key should it use?
• What URL does the application expose in order to receive tokens?
Each application is different, and not all applications need the same claims. One application might need to know the user’s groups or roles, while another application might only need a first and last name. So
when a client requests a token, part of that request includes an identifier for the application the user is trying to access.

This step might be different for each Issuer. For ADFS for example the ADFS management console allows you to added a relying party..using an “Add a trusted relying party” option. This would allow you to configure ADFS by telling it what claims you need etc. If you are using an Existing STS you will need to study its behaviour. Incase of custom STS using the VS templates you can customise in code and a lot of work is done by the FedUtil(Add STS ref) also.

Now that you know the overall steps in making an end to end claims aware app..we will get into some more details next time!

Until Then


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>