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


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…”.


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.


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!


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.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s