When you install an instance of Active Directory Federation Services v2, amongst other
things it will create a website within IIS to use as it’s Secure Token Service.
This is sort of fundamental to the whole design. There are some interesting
things to note about the situation though.
When Microsoft (or any ISV really) releases a new application or server that has a
website attached to it, they usually deliver it in a precompiled form, so all we do
is point IIS to the binaries and config files and we go from there. This serves
a number of purposes usually along the lines of performance, Intellectual Property
protection, defense in depth protection, etc. Interestingly though, when the
installer creates the application for us in IIS, it drops source code instead of a
bunch of assemblies.
There is a valid reason for this.
It gives us the opportunity to do a couple things. First, we can inspect the
code. Second, we can easily modify the code. Annoyingly, they don’t give
us a Visual Studio project to do so. Let’s create one then.
First off, lets take a look at what was created by the installer. By default
it drops the files in c:\inetpub\adfs\ls. We are given a few files and folders:
There isn’t much to it. These files only contain a few lines of code.
Next we create the actual project.
DISCLAIMER: I will not be held responsible if things break
or the server steals your soul. Please do NOT (I REPEAT) do NOT do this with
production servers please! (Notice I said please twice?)
Since we want to create a Visual Studio project, and since ADFS cannot be installed
on a workstation, we have two options:
Install Visual Studio on the server running ADFS
Copy the files to your local machine
Each options have their tradeoffs. The first requires a bit of a major overhaul
of your development environment. It’s very similar to SharePoint 2007 development.
The second option makes developing a lot easier, but testing is a pain because the
thing won’t actually work properly without the Windows Services running. You
would need to deploy the code to a test server with ADFS installed.
Since I have little interest in rebuilding my development box, I went with the second
Okay, back to Visual Studio. The assemblies referenced were all built on Framework
3.5, so for the sake of simplicity lets create a 3.5 Web Application:
I haven’t tested 4.0 yet.
Since this is a Web Application and not a Web Site within Visual Studio, we need to
generate the *.designer.cs files for all the *.aspx pages. Right-click your
project and select Convert to Web Application:
At this point if you tried to compile the application it wouldn’t work. We are
missing a few assembly references. First, add Microsoft.IdentityModel.
This should be in the GAC or the Reference Assemblies folder in Program Files.
Next, go back to the ADFS server and navigate to C:\Program Files\Active Directory
Federation Services 2.0 and copy the following files:
Add these assemblies as references. The web application should compile successfully.
Next we need to sign the web application’s assemblies. If you have internal
policies on assembly signing, follow those. Otherwise double-click the properties
section in Solution Explorer and navigate to Signing:
Choose a key file or create a new one. Rebuild the web application.
So far we haven’t touched a line of code. This is all general deployment stuff.
You can deploy the web application back to the ADFS server and it should work as if
nothing had changed. You have a few options for this. The Publishing Features
in Visual Studio 2010 are awesome. Right click the project and Publish it:
Since I set up a test box for ADFS development, I’m just going to overwrite the files
on the server:
Pro Tip: If you do something terrible and need to revert back to original code (what
part of don’t do this on a production box didn’t make sense? )
you can access the original files from C:\Program Files\Active Directory Federation
At this point we haven’t done much, but we now have a stepping point to modify the
default behavior of ADFS. This could range from simple theme changes to better
suit corporate policy, or to completely redefine the authentication workflow.
This also gives us the ability to better protect our code in the event that IIS craps
out and shows contents of files, not to mention the (albeit minor) performance boost
we get because the website doesn’t need to be recompiled.