The AD FS team at Microsoft has been adding interesting tools and utilities on https://adfshelp.microsoft.com which aid in troubleshooting AD FS sign-in issues. This will be the first blog in a series of blogs to demonstrate how you can use the different tools to effectively get around any federated sign-in issue. In this post, we will be detailing how Claims X-Ray can be used.
This tool can be used to debug and troubleshoot claims issuance related issues. If you deal with federated authentication, you can relate to the hair pulling situations where claims play havoc. You might be dealing with an already configured application / relying party or you might be setting up a new one. You figure out you need answers to the following:
- Does the token issued by AD FS has the right claims?
- If I change the authentication protocol, is there any impact on claims?
- If I change the authentication type, is there any impact on claims?
- The application / relying party can be rejecting the token if token signing certificate is not correct. Is the TS certificate correct and valid?
As you can see, there are multiple questions and in a non-ADFS Help world, it could involve multiple fiddler traces and substantial time investment. But Claims X-Ray can help you get the answers to all the above questions with-in no time and in very few clicks. So, let’s start the fun!
Setting up Claims X-Ray in your AD FS
Go to https://aka.ms/claimsxray and you will start with the first step of using Claims X-Ray – the setup.
Easy to use PowerShell commands are provided to configure the relying party (1) and the OAuth client (2). Copy the PowerShell commands using the copy button and paste it in a PowerShell window on your primary AD FS server. Since I am working with AD FS 2016, I have copied both setup commands for both relying party and OAuth client.
And with that, we are all set to use Claims X-Ray.
Uncovering the claims
Clicking on Next below the setup instructions, you can transition to step 2 – use the Claims X-Ray.
Some key points on this step:
- In the federation instance, provide your federation service FQDN, example fs.contoso.com
- Chose the authentication type like Forms based authentication, certificate etc. under Authentication Type.
- Select the protocol you want to enforce under Token Request.
- The toggle Force fresh authentication will to enforce fresh authentication and not use SSO.
Click on Test Authentication to test any credentials. Clicking on Test Authentication will open a new tab for authentication so that you can keep on changing the combinations and test different options without having to reload the page again.
In the new tab, the flow will be redirected to your AD FS like below:
Note: As your sharp eyes might have noticed, this is the new paginated experience for AD FS. You can access it here: https://aka.ms/adfsopensource under Azure AD Style Login Page
Getting all the answers at one place
Once you provide the credentials, Claims X-Ray will show all the information for the authentication request:
- Token Claims will list all the claims issued for the credentials
- Token Validity provides the token validity duration
- Token signing certificate details
As you can see, you can easily check the details of the token signing certificate and check if it is valid. Compare it with the configuration on the relying party / application side to ensure that the TS certificate is correctly configured. You can also easily download the certificate if required using the download button.
In the above steps, we used the default claim rule set by claims X-ray. If you are debugging issue on any other RP, you can simply copy the claims from the RP under investigation and then continue diagnosing the claims using the same steps as outlined above. Once you are done with the investigation, you can copy back the final set of claim rules after that to the original RP.
Try it out today! Leave any suggestions / queries / feedback in the comments section.