I’ve been working with AD FS for several years now and it’s become obvious that there are so many different scenarios and use cases for claims-based identity that it will rarely be a “point and click” deployment. I’ve seen a need for multiple tools that can tremendously help in this space. So, outside of my day job at Microsoft, I’ve been busy working on creating quite a few AD FS 2.0 tools. In this post, I want to introduce you to the first tool in this suite - ClaimGrabber. Before reading on, please note that this is something that I created on my own time and is not supported nor endorsed by Microsoft.
Testing Claim Rules
Often times when deploying AD FS and configuring Relying Party trusts, you author claim rules, but don’t really have an effective way to test them. The Claims UI in AD FS will help somewhat, providing syntax checking for claim rules for instance. But how can you test the rule itself to ensure that the resultant claims are what you expect? Sometimes, AD FS administrators will develop the claim rules in a separate lab environment and use a sample WIF application from the WIF SDK to test what claims are getting passed through. This has gotten the job done, but the process is laborious and you often don’t have access to the true source of the claim data in the lab environment. Also, this only provides insight into the claims being passed for the sample app, not other existing apps that trust AD FS.
Claims for Existing Relying Parties
This process for existing applications is also somewhat painful. If you’re federating with SharePoint 2010, you’ll build some claims rules and then see if they work as expected by trying to browse to SharePoint and see what happens. This is an inefficient way to test claim rules because many applications will not readily tell you what claims it was given. Also, if there is a misconfiguration on the application’s side or if you are authoring claim rules for future use, you won’t have a way to test them with the application until the application is ready to receive them and use them.
The other method for testing claims passed to existing RP trusts is to use a web debugger, such as Fiddler. If your Relying Party isn’t an application, but rather another federation service, you might use Fiddler to catch the POST method while it’s being passed through your browser and then dissect the SAML token manually. If you’ve done this, you’ll know that it’s not a lot of fun weeding through a bunch of XML and trying to find a couple of claims.
How ClaimGrabber Helps
This is the reason that I created ClaimGrabber. ClaimGrabber is an application that you run directly on one of the AD FS 2.0 servers. Basically, it impersonates both the user’s browser and application on the other end of the trust. ClaimGrabber is really simple to use; it’s only 3 steps and there is nothing you have to install:
- Select the application that you want to impersonate by choosing the corresponding trust from the drop down list
- Enter the credentials of the user that you want to see the claims for
- Click the “Grab Claims!” button
ClaimGrabber will attempt to log on by passing the application’s URN into the wtrealm query string parameter of the AD FS logon page’s URI. When AD FS responds with the web form that is used for POSTing the SAML token to the application, ClaimGrabber grabs the response stream and extracts the SAML token rather than processing the javascript auto-submit function. The claims extracted from the token are then displayed in the claim list inside the ClaimGrabber tool. Since the tool intercepts the POST-back, it doesn’t matter whether or not the application is actually accessible or even whether it’s a real application. Therefore, ClaimGrabber can be run against your existing list of RP trusts and show you what claim data is being sent to those RPs.
Requirements
Here are the requirements for running ClaimGrabber:
- ClaimGrabber must be run directly on one of the AD FS 2.0 servers
- The user account that launches ClaimGrabber must be an AD FS administrator. Please note that this is different from the account that you are using to log on to the RP with. ClaimGrabber allows you to specify the user that you log on with in the UI.
Improvements
There are a couple of things that the tool doesn’t do, but are on my list for a future update:
- Encrypted Tokens - Currently, ClaimGrabber cannot handle encrypted SAML tokens. In a later revision, I’ll give you the option of passing in the RP application’s encryption certificate containing the private key and have ClaimGrabber decrypt the token.
- Non-Active Directory Identity Providers - Right now, ClaimGrabber only authenticates users against the Active Directory claims provider. I plan on adding the capability to use other claims providers, including non-ADFS providers, in a future revision of the tool.
So download it, use it, and let me know if you come across any bugs or have suggestions for improvement. Feel free to comment on this blog post with them or send me an email at ken@identityguy.com.