A PowerShell script to find AD FS 2.0 errors

Posted by: Doug McDorman

So one of your users has received an error from AD FS 2.0, and you need to determine what the problem is. Unfortunately, sometimes the error message doesn’t give much of a clue—for example the web page shown below.

An error message presented to a user from AD FS 2.0

Fortunately, AD FS gives you a reference number that normally corresponds to some event log entries. If you do have one of these, you might find the following PowerShell script and associated launcher batch file useful to help find the actual entry quickly.

You can either edit the script to add all your AD FS servers or just run it on each AD FS server.

To run it you can simply double click on find-adfs-error.bat then type or paste in one of the reference numbers from an error page. Once you have found the exact event log entry, you might find it useful to look in the event log to see what else was happening near the time when the error occurred.

So here are the scripts. Take a look, and you might find some useful techniques. If you find them useful, please leave a comment. If you have questions, bring those too, and if you have suggestions for improvements, let me know about those as well.

Enjoy.

find-adfs-error.ps1

$ADFSServers = @($env:computername)
# Add your list of AD FS servers here (not proxies) to have this script search
# all your servers. The names should be the hostnames of the AD FS servers not
# the AD FS service name.
# Then uncomment the line with your servers by removing the leading #
# example: $ADFSServers = @("adfs01.example.com","adfs02.example.com")
#$ADFSServers = @("","")

Write-Host "Type or paste the reference number from an AD FS 2.0 error web page"
Write-Host "  this should be a string such as: 6906F0A7-BDF5-4EDB-B624-DE9CDAE7938F"
$userinput = Read-Host "Reference Number"

$CorrelationActivityID = $userinput.Trim()

$FilterXPath = "*[System/Correlation[@ActivityID='{" + $CorrelationActivityID + "}']]"
$LogName = "AD FS 2.0/Admin"
$DebugLogName = "AD FS 2.0 Tracing/Debug"
foreach ($ComputerName in $ADFSServers)
{

    try { #this requires "-ErrorAction Stop" on the commands
        $ADFSevent = Get-WinEvent -ComputerName $ComputerName -LogName $LogName `
            -FilterXPath $FilterXPath -ErrorAction Stop
        $ADFSevent | Format-list Id, MachineName, LogName, TimeCreated, Message

    }
    catch [Exception] {
        if ($_.Exception -match
            "No events were found that match the specified selection criteria") {
            # do nothing, it just means no events were found in this log
        }
        else
        {
            # Some other error happened so rethrow it so the user will see it
            Throw $_
        }
    }

    try { #this requires "-ErrorAction Stop" on the commands
        # You need to specify -Oldest when looking in Analytical and Debug/Trace logs
        $ADFSevent = Get-WinEvent -ComputerName $ComputerName -Oldest -LogName $DebugLogName `
            -FilterXPath $FilterXPath -ErrorAction Stop
        $ADFSevent | Format-list Id, MachineName, LogName, TimeCreated, Message
    }
    catch [Exception] {
        if ($_.Exception -match
            "No events were found that match the specified selection criteria") {
            # do nothing, it just means no events were found in this log
        }
        else
        {
            # Some other error happened so rethrow it so the user will see it
            Throw $_
        }
    }
}

If you want an easy way to launch the PowerShell script, try this batch file. Just double click on it, and off you go.

find-adfs-error.bat

powershell.exe -command ^
  "& {set-executionpolicy Remotesigned -Scope Process; .'.\find-adfs-error.ps1' }"
pause

References:

Diagnostics in AD FS 2.0
http://blogs.msdn.com/b/card/archive/2010/01/21/diagnostics-in-ad-fs-2-0.aspx

Configuring Computers for Troubleshooting AD FS 2.0
http://technet.microsoft.com/en-us/library/adfs2-troubleshooting-configuring-computers%28WS.10%29.aspx

To learn more about the PowerShell execution policy and code signing or signed scripts, open up PowerShell and enter the command:

Get-Help About_Signing

To make it easier for people to find these scripts, I’m including some keywords here that people might have been searching for. The keywords include Active Directory Federation Services, ADFS, event log, eventid, event viewer, correlation id or correlation identifier. There was a problem accessing the site. Try to browse to the site again. If the problem persists, contact the administrator of this site and provide the reference number to identify the problem. Reference number:

Tweet