While this module is used by the Azure AD Connect Health Agent, we have also published a copy of it in the AD Script Center. This way if you are not using the Azure AD Connect Health service, you have a way to run this locally on your AD FS servers.

The module file name is ADFSDiagnostics.psm1, is located under "%programfiles%\Microsoft AD Health Agent\Microsoft AD Diagnostics Service". Note that it requires elevated access, and PowerShell 4.0 to run. Below are the cmdlets available in the module:

PS C:\Program Files\Microsoft AD Health Agent\Microsoft AD Diagnostics Service> Get-Command -Module ADFSDiagnostics

CommandType Name ModuleName

----------- ---- ----------

Function Get-AdfsServerConfiguration ADFSDiagnostics

Function Get-AdfsServerTrace ADFSDiagnostics

Function Get-AdfsSystemInformation ADFSDiagnostics

Function Get-AdfsVersionEx ADFSDiagnostics

Function Receive-AdfsServerTrace ADFSDiagnostics

Function Set-ADFSDiagTestMode ADFSDiagnostics

Function Start-AdfsServerTrace ADFSDiagnostics

Function Test-AdfsServerHealth ADFSDiagnostics

Function Test-AdfsServerHealthSingleCheck ADFSDiagnostics

Function Test-AdfsServerToken ADFSDiagnostics

Let's take a look at the most important usage scenarios for the module. If you want to learn more about a specific cmdlet, you can use the Get-Help cmdlet to see detailed description and examples.

Performing AD FS Server Health Checks

This is perhaps the most useful during troubleshooting. The Test-ADFSServerHealth cmdlet contains a series of health checks for the most common AD FS issues with configuration that we have observed over the years.

We have different kinds of checks:

• Configuration/Best practices: Examples include SPN, DNS configuration, service account properties, etc.
• Certificate Properties: For example, whether a certificate is about to expire, CRL failed, etc. You can also do inspection on the relying party trust and claims provider trust certificates by setting the parameter "-VerifyTrustCerts" to $true (it is $false by default).
• Synthetic Checks: For example, retrieve federation metadata, and get a token from the STS). One thing worth mentioning here is that in order to have the synthetic transaction that gets a token from the STS using the actual server where the cmdlet is running, you should consider tweaking the host file to point to itself (either with IPv4 127.0.0.1 or IPv6 ::1) when resolving the AD FS host farm name. Otherwise, the synthetic transaction will go through the usual DNS resolution where another server will actually serve the request.
• Office 365 Specific Checks: For example, verify that endpoints required for office 365 to work are enabled, Relying Party trusts are configured, etc.. You can skip the office 365 checks by setting the parameter "-VerifyO365" to false (it is true by default).

Each result has the following properties:

• Name: Name of the test being run
• Result: This is the result of the test and can have a value of 'Pass', 'Fail' and 'NotRun'. A test might not run for a number of reasons such as OS version (IIS related checks only apply to ADFS 2.x), or role (Some tests only apply to a primary node on a WID farm).
• Detail: Explanation of the 'Fail' and 'NotRun' result. It is typically empty when the check passes.
• Output: Data collected for the specific test. It is a hashtable that contains a list of key value pairs with relevant data in the context of the test (for example, in the SPN test we add the service account name, the SPNs found in the service account, etc.,).
• ExceptionMessage: If the test encountered an exception, this property contains the exception message.

See an example below.

Test-ADFSServerHealth | ft Name,Result -AutoSize

Name Result

---- ------

IsAdfsRunning Pass

IsWidRunning Pass

PingFederationMetadata Pass

CheckAdfsSslBindings Pass

Test-Certificate-Service-Communications-Primary-NotFoundInStore Pass

Test-Certificate-Service-Communications-Primary-IsSelfSigned Pass

Test-Certificate-Service-Communications-Primary-PrivateKeyAbsent Pass

…

Test-Certificate-SSL-Primary-AboutToExpire Pass

CheckFarmDNSHostResolution Pass

CheckDuplicateSPN Pass

TestServiceAccountProperties Pass

TestAppPoolIDMatchesServiceID Pass

TestComputerNameEqFarmName Pass

TestSSLUsingADFSPort Pass

TestSSLCertSubjectContainsADFSFarmName Pass

TestAdfsAuditPolicyEnabled Pass

TestAdfsRequestToken Pass

CheckOffice365Endpoints Pass

TestADFSO365RelyingParty Pass

TestNtlmOnlySupportedClientAtProxyEnabled Pass

Gathering deployment information

The Get-AdfsSystemInformation cmdlet gathers general information about the server (OS, hardware, hotfixes installed, etc.). In the example below, I used a custom formatter so I can see some of the properties right out of the console output, which I find very useful when dealing with object in the pipeline that have complex data types:

Get-AdfsSystemInformation | fc -Depth 1

class PSCustomObject

{

OSVersion =

class Version

{

Major = 6

Minor = 1

Build = 7601

Revision = 65536

MajorRevision = 1

MinorRevision = 0

}

OSName = Microsoft Windows Server 2008 R2 Datacenter

MachineDomain = oneadhealthtest.com

IPAddress = 10.0.0.9

..

}

Similarly, the Get-ADFSServerConfiguration cmdlet gets more detailed information for AD FS Farm (Certificates, endpoints, etc.):

Get-AdfsServerConfiguration | fc –Depth 1

class PSCustomObject

{

ADFSSyncProperties =

class SyncPropertiesBase

{

Role = PrimaryComputer

}

ADFSAttributeStore =

class AttributeStore

{

…

}

ADFSCertificate =

[

@{Certificate=…

; CertificateType=Service-Communications; IsPrimary=True; StoreName=My; StoreLocation=LocalMachine;

Thumbprint=4AF5D7FD8934C08D1CF7C3D9C8394EB586606AA5}

@{Certificate=…

; CertificateType=Token-Decrypting; IsPrimary=True; StoreName=My; StoreLocation=LocalMachine;

Thumbprint=4AF5D7FD8934C08D1CF7C3D9C8394EB586606AA5}

…

AutoCertificateRollover = False

CertificateCriticalThreshold = 2

CertificateDuration = 365

CertificateGenerationThreshold = 20

CertificatePromotionThreshold = 5

CertificateRolloverInterval = 720

CertificateSharingContainer = CN=f056c184-835a-4fb8-9e0b-ebb421e8530f,CN=ADFS,CN=Microsoft,CN=Program

Data,DC=oneadhealthtest,DC=com

CertificateThresholdMultiplier = 1440

ClientCertRevocationCheck = None

…

}

ADFSRelyingPartyTrustCount = 5

ADFSClaimsProviderTrustCount = 1

..

}

Getting a token with specific credentials

We also added the cmdlet Test-ADFSServerToken, which you can use to get a token against the federation service. In the example below, we get a token against the "fs.contoso.com" AD FS farm, for the Relying Party identified by "urn:federation:MicrosoftOnline", providing a credential for the user we want to get the token for:

Test-AdfsServerToken -federationServer fs.contoso.com -appliesTo urn:federation:MicrosoftOnline -credential (Get-Credential)

cmdlet Get-Credential at command pipeline position 1

Supply values for the following parameters:

Credential

<s:Envelope xmlns:s="https://www.w3.org/2003/05/soap-envelope" xmlns:a="https://www.w3.org/2005/08/addressing" xmlns:u="h

ttp://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">…<…</s:Envelope>

Sometimes you may have a need to examine the contents of a token. For example, this could be to validate the issuance rules that you have configured for a specific relying party trust. You can use some PowerShell XML constructs to get the token as an object in the pipeline:

$token = Test-AdfsServerToken -federationServer localhost -appliesTo urn:federation:MicrosoftOnline -credential (Get-Credential)

$tokenXml = [Xml]$token

$tokenXml.Envelope.Body.RequestSecurityTokenResponse.RequestedSecurityToken.Assertion.AttributeStatement | fc -Depth 2

class 0:assertion#AttributeStatement

{

Attribute =

[

class 0:assertion#Attribute

{

Name = https://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid

AttributeValue = S-1-5-21-2474419537-1598421116-3968361607-513

}

class 0:assertion#Attribute

{

Name = https://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid

AttributeValue = S-1-5-21-2474419537-1598421116-3968361607-500

}

…

class 0:assertion#Attribute

{

Name = https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

AttributeValue = ONEADHEALTHTEST\healthadmin

}

class 0:assertion#Attribute

{

Name = https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname

AttributeValue = ONEADHEALTHTEST\healthadmin

}

]

}

Getting events based on Activity ID

AD FS (especially 2012R2) does a great job of writing events into the Windows event logs. When you hit an error (see image below), you may see an activity ID. Think of this as a transaction identifier and multiple events can be generated with the same activity ID. This gives an account of what happened on the AD FS servers when it processed the token request. When tracing is enabled, the # of events increase with more detail.

When troubleshooting issues and you have an activity ID handy, it is currently a challenge to go into each AD FS server and filter events looking for this activity ID. The script now makes it super simple for you.

You can run the Get-ADFSServerTrace cmdlet to find all the events related to that activity ID, across the different AD FS logs (Admin, Audits, and Trace). You can run this across multiple servers in just one command! Just populate the ComputerName parameter as an array of machine names, provided that you have enabled remote event log reading on them.

This example shows getting the activity Id from the error page above in the local AD FS server. Note below the "Source" property showing whether the event comes from audit or admin logs.

PS C:\adfsdiag> Get-AdfsServerTrace -ActivityId 00000000-0000-0000-886e-0080000000df

ComputerName : localhost

Source : Audits

TimeCreated : 2/12/2015 5:40:07 PM

EventId : 403

Message : An HTTP request was received.

Activity ID: 00000000-0000-0000-886e-0080000000df

Request Details:

Date And Time: 2015-02-12 17:40:07

Client IP: ::1

…

ComputerName : localhost

Source : Admin

TimeCreated : 2/12/2015 5:40:07 PM

EventId : 364

Message : Encountered error during federation passive request.

Additional Data

Protocol Name:

Relying Party:

Exception details:

Microsoft.IdentityServer.RequestFailedException: MSIS7065: There are no registered protocol handlers on

path /adfs/ls to process the incoming request.

…

ComputerName : localhost

Source : Audits

TimeCreated : 2/12/2015 5:40:07 PM

EventId : 404

Message : An HTTP response was dispatched with:

Activity ID: 00000000-0000-0000-886e-0080000000df

Response Details:

Date And Time: 2015-02-12 17:40:07

Status Code: 200

Status Description: OK

Sometimes it is useful to have it in a table format. For that, use the parameter OutHtmlFilePath, and the cmdlet will format the output to an HTML file and opens up the browser:

Get-AdfsServerTrace -ActivityId 00000000-0000-0000-ce70-0080000000df -OutHtmlFilePath .\report.htm

Report Generated at .\report.htm

Conclusion

The ADFSDiagnostics module is another tool in your toolbox to troubleshoot issues with your Hybrid environment. We are looking forward to your valuable feedback, either by signing up to the Azure Active Directory Connect Health or download the module stand-alone in the AD Script Center.
As we learn more about your scenarios and issues, and get feedback from you we will add more health checks, gather more data, and add more functionality to make your life easier and your Hybrid Deployment in good shape!

On this post I will describe in a nutshell the "Usage analytics" capability of the new Microsoft Azure AD premium feature "Azure Active Directory Connect Health" and how it can be used to gain insight into the traffic of your on-premises identity infrastructure.

Current AD FS Auditing story

AD FS auditing is a very useful tool for AD FS administrators to monitor closely the AD FS traffic.

Unfortunately, the value of this auditing tool is often times not fully exploited by organizations due to the large amount of data that it generates and due to the fact that this data requires a deep understanding of AD FS concepts and must be parsed in order to discern each AD FS transaction and its corresponding outcome.

For example; the image below shows the event log entries generated by the AD FS auditing on a Windows Server 2012 R2 Federation Server.

The highlighted events correspond to a single WS-Trust Authentication request.

An AD FS request is processed by multiple subcomponents within the STS. These could be: receiving the HTTP request, decoding the headers, authorizing the caller, issuing the corresponding set of claims etc. Each of these subcomponents generate distinct audit events therefore, there is no single audit event that summarizes all the request's attributes.

In this particular case:

• Event 403 specifies the client IP
• Event 410 specifies the ADFS endpoint
• Event 431 specifies the key type
• Event 500 specifies the Issued identity
• Event 501 specifies the caller identity (among other things).

In order for an AD FS administrator to determine all the attributes of a "logical login transaction" (this AD FS WS-Trust request), these audits must be associated to each other through the "Correlation ID" and "Activity ID" fields included on each event log entry. As you can imagine, this process can be tedious, error prone and time consuming.

"Usage Analytics" feature of "Azure Active Directory Connect Health"

When the "Azure Active Directory Connect Health" agent is installed on any supported AD FS STS (we support ADFS 2.0 on Windows Server 2008R2 as well as ADFS in Windows Server 2012 and 2012R2), the agent takes on the burden of parsing and understanding the contents of the AD FS Audit logs away from the administrator and uses the power of the "Azure AD Connect Health" cloud service to analyze and present the traffic of your AD FS infrastructure in a user friendly format.

Here is how it works:

As explained above, multiple AD FS Audits are created on the AD FS STS through the lifecycle of an AD FS transaction. Whenever an audit is created, the "Azure Active Directory Connect Health" agent dissects its contents and uses its "Activity ID" and "Instance ID" to create a "Logical AD FS Audit". As audit events come by, this logical audit will be updated to ultimately contain all the relevant information of each AD FS request such as Relying Party, Server Name, Authentication Method etc. (for security purposes, the agent does not include PII on the "logical audit").

At regular intervals, the "Azure Active Directory Connect Health" agent will take all the "Logical AD FS Audits" it has constructed so far and upload them to the "Azure Active directory Connect Health" service.

Every 15 minutes, the cloud service will aggregate the data that has been uploaded by all "Azure Active Directory Connect Health" agents installed on all the AD FS servers across the AD FS farm and update the "Usage Analytics" views to offer "Insights" into the identity traffic such as "Top application visits", "Total Requests by server", "Average unique users by Relying Party" (amongst others):

At the moment, the service offers two pivots to look at your data: "Total number of Requests" or "Unique User Count", each one of which has a different set of "Groupings":

I hope you will find this new Azure Active Directory Premium feature a valuable addition to your identity control plane.

Please try it out, as always, we'd love to hear any feedback or suggestions you may have.

For additional documentation, including step by step installation, please go to https://msdn.microsoft.com/en-us/library/azure/dn906722.aspx

Regards