AD FS Events Module – swift and powerful AD FS event log analysis

Folks,

Today’s post is going to be very interesting. I am super excited because I can see the unlimited potential this new tool has created. Say hello to AD FS Events module. Some of you might be already using it or have tried it earlier. The new additions to the functionality take it to a whole new level.

The AD FS Events module was created by the Microsoft AD FS team under the AD FS OpenSource initiative. One of the key issues in AD FS troubleshooting has been the necessity to look at so many log events for any particular request under investigation. The problem is not that there are fewer logs, the problem is too many logs. AD FS Events was developed to help you make sense out of logs for a particular request under investigation at a faster pace. Let’s see how.

Imagine you have an issue occurring with an application federated with your AD FS and on the AD FS error page, you get the normal message: “Something happened, contact your administrator. Activity ID: 983asduo23804820-123123-12312…”.

loginfedpassive1loginerror

In usual circumstances, if the administrator is contacted and given just a correlation ID the odds are that you and the administrator are not going to remain buddies anymore, after all, who loves tracking down a correlation id among a pile of event logs? But if you use AD FS Events module – the process is simple. Here we go –

Go to your AD FS server and load the AD FS Events PowerShell module. Then, with one single command go over ALL the AD FS servers in your farm (because you don’t know which AD FS server ended up servicing the request) and grab the relevant events. Not just grab the events, but create a PowerShell object with all the relevant details of the error.

command

PS C:\temp> Get-ADFSEvents -CorrelationID 1117a09f-e431-4cef-fe14-0080000000e5 -Server server1,server2,...,serverN -CreateAnalysisData | Write-ADFSEventsToTable

Let us see the important parts of the command and understand what they are doing

CorrelationID: This is the correlation ID user saw on the AD FS error page
Server: You can mention all the AD FS servers that AD FS Events module should look for events. (A future update will let you specify a ‘*’ in a 2016 farm and it will automatically go over all the servers as per configuration)
CreateAnalysisData: This flag tells AD FS events to not just grab the events but create the analytics table

This is the schema of the analytics object created:

TypeName: System.Management.Automation.PSCustomObject

Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
AnalysisData NoteProperty System.Management.Automation.PSCustomObject AnalysisData=@{requests=System.Object[]; responses=Sys...
CorrelationID NoteProperty string CorrelationID=1117a09f-e431-4cef-fe14-0080000000e5
Events NoteProperty psobject[] Events=System.Management.Automation.PSObject[]

Further drill down of the AnalysisData property gives us

TypeName: System.Management.Automation.PSCustomObject

Name MemberType Definition
---- ---------- ----------
Equals Method bool Equals(System.Object obj)
GetHashCode Method int GetHashCode()
GetType Method type GetType()
ToString Method string ToString()
errors NoteProperty Object[] errors=System.Object[]
requests NoteProperty Object[] requests=System.Object[]
responses NoteProperty Object[] responses=System.Object[]
timeline NoteProperty Object[] timeline=System.Object[]
ver NoteProperty string ver=1.0

As you can see, it has all the relevant details of the request – including the headers! Amazingly helpful, right? As you might have noticed, I piped the output to the Write-ADFSEventsToTable function. This is a quick 100 line code that one of my colleagues wrote to take advantage of the analytics information created by AD FS Events module. The result is the relevant information in an HTML format!

output1error

Of all the events, I can clearly zoom in to the error event and find the root cause faster than ever. Not just that, I have the view of all request and responses for the particular correlation id and can easily see the query parameters and headers without opening fiddler.

Exciting, right? Give it a shot and see it in action yourself. It is available on AD FS Help now. This can be a very powerful tool and help you cut down investigation time drastically.

Got some crazy idea on how to use the analytics object created? Go ahead and start contributing to the AD FS OpenSource project now! Leave your feedback in the comments section.

Claim rules for Azure AD federation trust

Hey folks!

First and foremost, thanks for the feedback that is coming through, it is super helpful. Please keep it coming.

In today’s post, I am going to talk about the changes we have done to the Azure AD Claims tool on AD FS Help. Azure AD Connect is the tool recommended for managing your federation trust between AD FS and Azure AD. The AD FS team at Microsoft keeps on improving the management feature of federation trust in Azure AD Connect to make sure it is robust and up-to-date w.r.t. the latest guidelines and features. One of the key aspects is the required set of claim rules on the federation trust. Azure AD Connect makes sure the claim rules and settings of the federation trust between Azure AD and AD FS are always in compliance with the latest guidelines.

If for some very compelling reason you cannot manage your federation trust with Azure AD Connect, you can now use Azure AD Claims to generate the right set of claim rules for your federation trust. Whether you are setting up a new federation trust, re-creating or repairing, you can use the tool to ensure you have the same set of claim rules as Azure AD Connect provides.

With the latest changes to the Azure AD Claims tool, you can choose the sourceAnchor and userprincipalname similar to the options you get in Azure AD Connect.

sourceAnchor

userprincipalname

Apart from the sourceAnchor and alternateID scenario, one of the most error-prone areas is getting the claim rules right in a multi-domain federation scenario. Again, Azure AD Connect takes care of the multi-domain federation and claims required when you manage your federation trust with it. Coming back to Azure AD Claims, the AD FS Help has now made it super easy to provide input about your federated domains. Simply copy the PowerShell script provided and upload the resulting CSV to AD FS Help. As soon as you upload the CSV, a table will list the domains and you can edit the list of domains as required:

domains

domainlist

Click on Generate Claims will generate the required claims tailored to your configuration as per the input provided.

generatedclaims

The output is divided into 3 parts for your reference:

  1. IssuerID Regex: if this is the only part you are trying to confirm in case of multiple domain federation, this is the only info you are looking for.
  2. PowerShell for Claims: Easy PowerShell script for setting the resulting claims on federation trust in your environment.
  3. Claim Rules: Individual claim rules listed for easy reference.

Super cool right? Try it out and provide your feedback.

 

Claims X-Ray

Hello folks!

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:

  1. Does the token issued by AD FS has the right claims?
  2. If I change the authentication protocol, is there any impact on claims?
  3. If I change the authentication type, is there any impact on claims?
  4. 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.

setup1

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.

setup2

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.

claimsxray1

Some key points on this step:

  1. In the federation instance, provide your federation service FQDN, example fs.contoso.com
  2. Chose the authentication type like Forms based authentication, certificate etc. under Authentication Type.
  3. Select the protocol you want to enforce under Token Request.
  4. 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:

token1

  1. Token Claims will list all the claims issued for the credentials
  2. Token Validity provides the token validity duration
    token2
  3. Token signing certificate details
    token3
    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.