I recently spent a painful 30-40 hours setting up VPCs according to the Tech Net lab "Step-By-Step Guide for AD FS in Windows Server 2008. The lab is located online here: http://technet2.microsoft.com/windowsserver2008/en/library/87e1a178-4d8a-4e89-98b0-d125f9c84c221033.mspx?mfr=true

In fact, the process didn't have to be so painful except that there are just a few instructions that are less than clear, incomplete or incorrect. Of course, when things don't work as expected I automatically assume that I missed a step, executed a step incorrectly, or just plain didn't know something that the lab instructions assumed everyone knows. So, my natural instinct was to repeat the steps, which I did several times spending many hours since there are 4 VPCs and lengthy installation steps involved for each. As it turns out, just a few fixes to the lab instructions could have avoided all that.

A document summarizing the issues can be downloaded from here, with additional screenshots beyond what is discuss below: http://www.dasblonde.net/downloads/ADFSServer2008LabErrata.pdf.

I hope you find this helpful if you are trying to follow the lab. If you encounter different problems, please do let me know so I can post updates here.

Step 1: Preinstallation Tasks

• Section: Configure computer operating systems and network settings
  • Before you get started, make sure to turn off the firewall settings on all VPCs. The firewall gets in the way of DNS resolution between machines which causes problems with adding computers/users to domains, problems browsing to sites later on in the lab, and similar problems with redirections that take place when you run the lab.
  • During network setup, you don’t need to select server roles yet even though the chart lists them. Just set up the IP addresses at this time. The table listing is just a little misleading as it might lead you to think you need to set up the web server, federation server or domain controller at this point, but there are separate steps for this later.
  • Set IP addresses according to the table for IPv4 and disable IPv6. If you don’t disable IPV6, the AD DS setup will try to enable dynamic DNS and then your static IPs will be blown away.
• Section: Install and configure AD DS
  • The firewall on the adfsaccount machine must be off for this to work.
  • After installing AD DS, check your network IP settings again just to make sure the DNS settings are as you set them in the previous step. I found that sometimes the preferred DNS settings were reset.

Step 2: Installing AD FS Role Services and Configuring Certificates

• Section: Configure IIS to require SSL on both federation servers
  • You can skip this step completely!!!! After you install AD FS there is a new web application directory created under /adfs. The /ls subdir is already set up to require SSL and Ignore certificates. The /fs subdir is already set up to require SSL and Accept certificates. You don’t need to do anything more here. In fact, if you execute this step and set up the default web site to Accept certificates you’ll be prompted to supply a client certificate when you browse to the claims-aware application later on. This will not only confuse you, but prevent you from browsing to the claims-aware application successfully.
• Section: Export the adfsresource server authentication certificate to a file
  • There is no reason that you have to export the private key (.pfx) here. To establish trust only the public key cert (.cer) is required. Following the lab steps won’t hurt you here, but it is important to understand that exporting private keys is not traditionally recommended outside of the machine, domain or application that owns the key.
  • This also implies that the next section could import a .cer instead of a .pfx, depending which route you take.

Step 3: Configuring the Web Server

• Section: Configure IIS on the Web server
  • After completing step #7 to require SSL for the default web site, skip step #8. Leave the setting as require SSL and Ignore client certificates. You don’t want to Accept client certificates, this causes the browser to prompt for a certificate when you browse to the claims-aware application.
  • In fact, step #7 could be modified so that you don’t require SSL for the entire Default Web Site. Instead, you could just require SSL for the /claims-aware application directory which we will be browsing to.
• Section: Create and configure the claims-aware application
  • These instructions are fine, but the files from the Appendix A are incorrect for IIS 7. See my notes on this later on.

Step 4: Configuring the Federation Servers

• These steps are fine, but after you have completed these steps you’ll have to do a few more certificate installations to ensure self-signed certificates are trusted on appropriate machines. I have provided instructions on that below.

Running the AD FS Diagnostic Tool

• When I was trouble-shooting my own lab issues, Joe Kaplan pointed me to the AD FS Diagnostic Tool which is blogged about here: http://blogs.technet.com/adfs/archive/2007/11/01/adfs-diagnostic-tool.aspx. This really helped me to verify certificates were trusted, and that my AD FS configuration was ok. Run this tool and follow the instructions on the blog post. Note the following:
• You will get warnings on the resource server related to E-mail claims, but those do not cause any concern, just ignore it.
• If you do get any errors, fix the problems indicated in the error. I only encountered one or two errors related to self-signed certificate trust, which I explain how to fix in the next section.

Additional Configuration for Self-Signed Certificates

• Since you are using self-signed certs on all machines, it is best practice to install your public key certs into the Trusted Root Certification Authorities store on the machine that owns the cert, and on any machine that must trust the cert. Some of the lab steps address this, but there are a few missing steps and again this can confuse you if you aren’t familiar with certificate issues.
• The following instructions guide you first through exporting the certificates we need to work with. You may have already exported these certs in previous steps, and hopefully are using the same naming convention specified in the lab.

Exporting certificates, if you haven’t already:

• Machine: adfsaccount
  • The private key created for IIS is installed in the Local Machine/My store, called adfsaccount.adatum.com. Export the public key certificate (.cer) if you haven’t already and call it adfsaccount.cer.
  • The private key created for the federation server to sign tokens is installed in the Local Machine/My store, called Federation Server adfsaccount. Export the public key certificate (.cer) if you haven’t already and call it adfsaccount_ts.cer.
• Machine: adfsresource
  • The private key created for IIS is installed in the Local Machine/My store, called adfsresource.treyresearch.net. Export the public key certificate (.cer) if you haven’t already and call it adfsresource.cer.
  • The private key created for the federation server to sign tokens is installed in the Local Machine/My store, called Federation Server adfsresource. Export the public key certificate (.cer) if you haven’t already and call it adfsresource_ts.cer.
• Machine: adfsweb
  • The private key created for IIS is installed in the Local Machine/My store, called adfsweb.treyresearch.net. Export the public key certificate (.cer) if you haven’t already and call it adfsweb.cer.

Importing certificates, if you haven’t already:

• Machine: adfsaccount
  • Import both adfsaccount.cer and adfsaccount_ts.cer into the Local Machine/Trusted Root Certification Authorities store.
• Machine: adfsresource
  • Import adfsresource.cer, adfsresource_ts.cer and adfsaccount.cer into the Local Machine/Trusted Root Certification Authorities store.
• Machine: adfsweb
  • Import adfsweb.cer into the Local Machine/Trusted Root Certification Authorities store.
• Machine: adfsclient
  • In Step 5 you will be asked to install certificates through the browser. This should work just fine for you, thus no need to manually install to the certificate store. In the event you have issues, or if your client is not Vista o XP, you may need to manually install the certificates to trust the downstream services.
  • Import adfsaccount.cer, adfsresource.cer and adfsweb.cer into the Local Machine/Trusted Root Certification Authorities store. This tells IE that the web sites can be trusted even though the certificates are self-signed.

Step 5: Accessing the Sample Application from the Client Computer

• This is the section where I began to have issues, which of course led me to retracing my steps several times unnecessarily as it turned out since the problems were related to a few missing or incorrect steps.
• DNS Resolution:
  • The first problem I encountered was DNS resolution to adfsaccount. I consulted my friend Stephen Rose for this one, and we literally spend hours reviewing each VPC and its IP and DSN configuration, looking for issues. I learned a lot about DNS in the process (Stephen is the man) but we still ultimately had problems pinging one of the machines. As it turned out, the issue was the firewall was still on for one of the machines. Somehow we failed to see that.
  • Make sure you can ping each machine from the adfsclient machine using not just IP address, but actual DNS – check your firewall settings first if you can’t, then check your IP/DNS settings on each machine to match Step 1:
    • Ping adfsaccount.adatum.com
    • Ping adfsresource.treyresearch.net
    • Ping adfsweb.treyresearch.net
  • If DNS is working, you shouldn’t have any issues with the steps in this section of the lab.
• Requiring a Client Certificate:
  • The second issue I encountered was the client certificate issue. When I browsed to the claims-aware application, IE kept prompting me for a certificate with an empty dialog since I had no certificates. I consulted my friend Joe Kaplan for this, thinking I was missing something in my configuration. We extensively reviewed my setup, and in the process stumbled on the IE settings for Accept certificates. He educated me that the adfs/ls and /adfs/fs directories were already set up properly when you install AD FS on the machines…so I rolled back the step that incorrectly configured each web site for the Accept setting.
  • If you skipped the step to configure the web sites to require SSL and Accept certificates, you should be able to get through the steps in this section of the lab as well.
• Section: Configure browser settings to trust the adfsaccount federation server
  • You should get a certificate error in this step, since the certificate is self-signed. When prompted you can to install the certificate as instructed for the adfsweb site in a later step.
• Sections: Access the claims-aware application from a Windows XP client/Vista client
  • Either of these sections should behave similar though instructions to handle self-signed certificates are slightly different.
  • You may be prompted more than once to install certificates, as you are redirected to the adfsresource and adfsaccount servers. Be prepared to install several certificates.

Appendix A: Creating the Sample Claims-Aware Application

• The code for default.aspx and default.aspx.cs are fine in this section of the lab.
• The web.config does not work for IIS7, and this can really throw you for a loop because you’ll get a generic “Internal Server Error” at the client machine…with NO IDEA what is behind it. This happened to me and I assumed once again that I had missed a configuration step. Joe Kaplan and I spent a bunch of time trying to trouble shoot my configuration for AD FS on all machines, thinking that was the cause…and then he eluded it might be an IIS issue. It turns out that if you browse to the /claimapp from the web server machine you can see the full error. Thanks to my friend Richard Campbell for suggesting I try that one! Since I have custom errors turned off in the web.config, I should have been able to see the error remotely…but apparently something else (perhaps in IIS 7 defaults) is overriding that behavior. I’ll have to look into that separately.
• When I was able to see the full error, it pointed to a configuration issue in the web.config related to the HTTP module configuration for the Web Agent (screenshot below). A new section must be added to the web.config, inside the <configuration> element, as follows:

<system.webServer>
  <modules>
    <add name="Identity Federation Services Application Authentication Module" 
type="System.Web.Security.SingleSignOn.WebSsoAuthenticationModule, 
System.Web.Security.SingleSignOn, Version=1.0.0.0, 
Culture=neutral, PublicKeyToken=31bf3856ad364e35, Custom=null" 
preCondition="managedHandler" />
  </modules>
  <validation validateIntegratedModeConfiguration="false" />
</system.webServer> 

I have to say, it was an interesting ride trying to get this lab set up, and as it turns out there aren't too many errors in the lab but the few missing and incorrect steps was enough to cost me 30 extra hours at least of preparation time. I hope you do not have the same problem with the tips I have provided here. I have to thank once again my friends Stephen, Joe and Richard for their respective roles in helping me work through the issues. Especially Joe who really went out of his way to help me review the AD FS setup, even though it turned out that the lab was not incorrect on that front...he gave me lots of great insight in the process, not to mention some cool tools that I could use to troubleshoot. You guys are the best!!!!

Supporting Resources:

• Joe Kaplan is one of the very few and strongest authorities on AD FS out there today, and he was a tremendous help to me as I got up to speed on the environment. His web site and forum are as follows:
  • http://www.joekaplan.net
  • http://directoryprogramming.net
• ADFS for Developers – a nice high level article from Keith Brown on ADFS (for 2003 server):
  • http://msdn2.microsoft.com/en-us/magazine/cc163520.aspx
• Understanding WS-Federation – to understand the protocols beneath federation, this is helpful:
  • http://msdn2.microsoft.com/en-us/library/bb498017.aspx