Establishing a production federation between different organizations can be challenging.  A successful federated connection depends on numerous configuration and policy details being setup correctly at both ends.  If an application request fails, it can be difficult to track the failure back to an underlying configuration error, especially since an administrator at either partner only has access to half of the end-to-end system data.

Like most products Active Directory Federation Services provides trace logs to help solve these kinds of problems.  However, as any seasoned sysadmin knows, a high-level application request can spawn a multitude of underlying protocol messages.  Finding a single setup error by combing through the associated debug logs is tedious at best, and impossible if you do not know what to look for.  

The ADFS Test Team has filled the gap with tooling to verify that the underlying federation infrastructure is setup correctly.  They developed a new ADFS Diagnostics Tool that is available for free download on the web.  Administrators at each end of an ADFS-based federation can run the tool, share the output files, and quickly pinpoint configuration problems at their security token services (STS).  If ADFS is only used by the Relying Party partner in the federation, the tool can still be used to diagnose configuration problems between the STS and the application server.  One of Microsoft’s premier support engineers has posted the tool and provided a space for customers to ask questions and provide feedback.  He has high praise for how easy it is to perform low-level diagnostics of the complete distributed system.

The tool is very simple to use and provides a graphical UI. In order to perform distributed diagnosis, i.e. diagnose failures based on the configuration of multiple machines in the scenario, it’s necessary to copy the out file generated by the tool each time it’s run and use it as an input/output file when running the tool on the next machine.

For example, to debug a scenario with an FS at the account role (FS-A), an FS at the resource role (FS-R) and a Web Server (WS), first run the tool on the FS-A selecting a new file, say adfsdiag.out. After the tool is run, this file will now contain configuration information relative to the FS-A. Copy the file to the FS-R machine and run the tool there, this time selecting the existing adfsdiag.out file. The tool will detect it already contains information relative to other roles and will execute extra configuration checks, for example, a claim flow check that verifies the outgoing claims sent by the FS-A match the incoming claims expected by the FS-R. After this second run, adfsdiag.out will contain information relative to both the FS-A and FS-R. Finally, copy the out file to the WS machine and run the tool again following the same steps.

A number of large scale, production ADFS deployments came on line towards the end of last year.  Many more are in the pipeline.  This free tool has already proven to be priceless.  Try it and see for yourself.