First of all you should start by downloading the Windows Identity Foundation (aka WIF) from Microsoft. This download provides all the necessary dlls (including System.IdentityModel and Microsoft.IdentityModel) to build a WIF claim based application.
The second thing you have to do is download the Windows Identity Foundation SDK that integrates into visual studio and provides many helpful examples. This download provides the FedUtil.exe also known as Federation Utility that automatically configures the trust between an RP and an STS and also auto generates a custom STS based on your RP configuration file.
Having installed the two prerequisites, you may download the sample project I have created, from the following link, and look for the comments that start with “WIF Comment:” in order to locate the code that is WIF specific.
As I mentioned earlier I wanted to create a simple claim based web site application (see a couple of reasons on why you may need to create one on my previous post). In fact the downloaded solution contains two relying parties. One (RelyingParty) that was manually created from start to end (ok I admit that the design is created by vs) and another one (AutoconfiguredRelayingParty) that was configured almost entirely by the Federation Utility that comes with the WIF SDK. Let’s see the RelyingParty project first.
The RelyingParty (RP) web application
This is the default asp.net application that was created from the visual studio templates. I have stripped off the entire FormsAuthentication mechanism that comes with the original template (deleted the appropriate folder) and modified the web.config to enable the WS Federation Authentication.
One thing you should note is that we have completely disabled the asp.net’s build in authentication by setting the mode to None and on the other hand we have denied unauthenticated users by setting «deny users="?"». The next thing we did was to add the WS Federation httpmodules in the asp.net’s modules stack (under the httpModules for IIS6 and the webdev server visual studio runs and under system.webServer.Modules for IIS 7+). These modules will be handling the authentication requests of our application. In order to configure them we will have to introduce a new configuration section in our web.config file by adding the corresponding section declaration in the configSections region on the top of our configuration file. We added the microsoft.identityModel section which is heavily commented in the downloaded source code. The most important parts of this section are:
- The applicationService\claimTypeRequired part where you specify the claims your application requests from the STS.
- The passiveRedirectEnabled="true" set in the wsFederation section that enable the passive redirect to the STS whenever authentication is required
One final thing you should note in the web.config file is the requestValidationType="WIFCommonLibrary.Web.AllowWFClaimsRequestValidator" set in the httpRuntime. By overriding the request validation, we will be allowing the federation form requests that will be coming into our application. If you don’t do so, you will get a «A potentially dangerous Request.Form value was detected from the client (wresult="trust:RequestSecuri..."» error due to the default asp.net’s request validation that prevents suspicious requests.
The SecurityTokenService (STS) web application
The STS consists of two web pages:
- The default.aspx which will be creating the federating identity and
- The login.aspx which will be authenticating the incoming users.
The STS is a simple web application (in a manner of speech). If you take a look in the web.config, perhaps you will be surprised to see that there is no identity configuration. It only contains a simple FormsAuthentication declaration. In order to keep the demo simple, I have decided to use asp.net’s default forms authentication in order to verify my users. This means that you can simply add your own membership provider and verify the users on any source you like. One more thing you have to note is that I don’t allow any unauthenticated user to see the default page (the one responsible for creating the federation token). This means that when the RP calls the STS for a security token, the request is automatically redirected to the STS’s login screen where the user has to present his credentials, and then he is redirected to the default page which redirects the user back to the RP passing the security token. This is depicted in the following sequence diagram:
The default page contains the code that handles the federation requests (signin and signout) and there are not many things you should modify in this page. The hard work of the STS is located in the folder SecurityTokenService where the customsecuritytokenservice is defined.
CustomSecurityTokenServiceConfiguration refers to the configuration of the STS and provides a single instance access of this configuration (thus you’ll not have to set the security token service’s configuration over and over again). Note that we initialize the STS’s certificate calling the CertificateUtil.GetCertificate() method which retrieves the certificate from the embedded resources. In the actual production STS you should retrieve the certificate from the computer’s certificate store!
CustomSecurityTokenService is the actual STS. It inherits Microsoft.IdentityModel.SecurityTokenService.SecurityTokenService, it handles the requests and provides the requested ClaimsIdentity based on the authenticated user’s properties. To keep this demo simple, I have hard coded the output claims, but you should probably add some database lookup mechanism in order to retrieve each user’s claims. The place to add this kind of mechanism is the overridden GetOutputClaimsIdentity method.
The last file you should probably see is \FederationMetadata\2007-06\FederationMetadata.xml which is a descriptive metadata file of the STS’s capabilities. It describes in the oasis standards what are the available claims, who is responsible for this STS, how can you access this STS and staff like that. In order to create these files please refer to the WIF Custom STS metadata file editor I have created in a previous post.
The AutoconfiguredRelayingParty (RP) web application
Having created the STS you may now have the Federation Utility (found in the WIF SDK) to automatically configure your RP. To demonstrate this functionality I have created another empty asp.net web application and used the tool to pair it with my new STS. To see how this is done, please refer to my older post found here.
The only thing you should note is that you’ll have to manually set the requestValidationType to allow the federation token form posts, as mentioned in the previous relying party (or you can see the web.config comments).
The WIFCommonLibrary library
This library contains some useful classes that I have gathered together in order to facilitate the development of custom STSs and RPs. They are only for developing and testing purposes and should never be used in the actual production applications. Both available classes are discussed in the previous sections of this article.
Hope this article and the source code will help you get started with the windows identity foundation!