How to associate a web application (RP) to an existing Security Token Service (STS) using Federation Utility (FedUtil.exe)

Federation utility is a very nice little tool that can automatically configure your claim based web application (which is called Relying Party or RP in the Federation language) to trust an existing security token service (STS). It comes with WIF SDK available from Microsoft. This tool can also create a new STS based on your own claim based web application, but this is not on the scope of the current post.

In order to establish the trust you’ll have to do the following steps:

Right click on you project and select the “Add STS Reference…”. If you haven’t got the WIF SDK extensions installed on your computer, you may run the tool from C:\Program Files (x86)\Windows Identity Foundation SDK\v4.0\FedUtil.exe (removing the x86 on x32 operating systems).

Fill in your RP application info and click next.

On this stage you may face the following error (unless you have your website on a secure https layer):

Locate the STS’s Federation Metadata xml file (usually located on http://sts-address/FederationMetadata/2007-06/FederationMetadata.xml) and click next.

On this stage you may receive up to three warnings depending on your STS’s security settings.
The first one refers to the lack of digital sign on the federation metadata file.

The second one refers to the lack of an https endpoint on the service. If you want to avoid this message, then you should probably have an ssl installed in the hosting computer that serves the STS.

The third warning refers to the lack of valid certificate on the STS. If your server runs on a developing certificate, the tool will not be able to validate the certificate. That’s ok on dev environments but should not be the case in production level.

On the next screen you will be prompted to provide a certificate for your own claim based application. You may specify the certificate with which the STS will be encrypting the communication between the RP and the STS. The point of this certificate is to encrypt the messages in a way that only the requesting RP will be able to understand. If you leave this blank, then the messages will not be encrypted.

Clicking next you will see the available claims on the STS. Nothing to do here…

The final step is the overview.

Click finish and you are done.

Let us test the application. Clicking debug you will actually reach the STS, do the authentication and by the time you come back to your claim based application you receive an ugly message «A potentially dangerous Request.Form value was detected from the client (wresult=»

In order to fix this error you must modify the web.config and set an http runtime request validator that allows the federation messages to pass through. For example it would look like the following statement:

httpruntime requestvalidationtype="WIFCommonLibrary.Web.AllowWFClaimsRequestValidator"

(You may download the implementation of this custom Request Validator from this post)

That’s it, your RP is configured to trust the new STS. You may change the requested claims from your web.config file.

Happy federation!