Configuring Computers for Troubleshooting AD FS 2.0

Updated: May 5, 2010

Applies To: Active Directory Federation Services (AD FS) 2.0

Before you use advanced troubleshooting techniques to identify and fix Active Directory Federation Services (AD FS) 2.0 problems, configure your federation server or federation server proxy computer or computers for diagnosing issues that might require troubleshooting.

Preparation tasks for diagnosing AD FS 2.0 issues

To configure your computers in preparation for diagnosing AD FS 2.0 related issues, you should perform the following tasks:

• Set up AD FS 2.0 event logging

• Configure debug tracing for AD FS 2.0

• Configure auditing for AD FS 2.0

• Configure performance monitoring for AD FS 2.0

Set up AD FS 2.0 event logging

Before you make configuration changes for troubleshooting AD FS 2.0, use Event Viewer to verify that AD FS 2.0–related events are appearing in application logs. By default, AD FS 2.0 uses a verbose level of logging that includes logging of all errors, warnings, and informational events. To ensure that you are using event logging to diagnose a problem, you can verify or reconfigure the AD FS 2.0 log level by using Event Viewer or, for command-line management using Windows PowerShell for AD FS 2.0, by using the LogLevel parameter in the Set-ADFSProperties cmdlet.

To filter for any AD FS 2.0-related events

1. Open the Event Viewer snap-in.

   To open Event Viewer, click Start, point to Administrative Tools, and then click Event Viewer.

2. In the console tree, expand Applications and Services Logs, expand AD FS 2.0, and then click Admin.

3. In the Filter Current Log dialog box, for Event level, verify that the following check boxes are selected for these levels of events: Warning, Information, and Error. Click OK.

   The details pane is filtered to show all events that might be problems or support issues that are related to AD FS 2.0.

At this point, you should focus on reviewing any events that appear in the filtered log. These events might indicate a potential service-level issue with AD FS 2.0. In some instances, you may want to use the Get-ADFSProperties cmdlet to verify the current LogLevel setting. By default, the LogLevel value that AD FS 2.0 uses when it is first installed is equivalent to Verbose, Error, Warning, and Information.

Verbose logging allows for full unfiltered logging of all errors and warnings that might occur, depending on the configuration choices that you made in your AD FS 2.0 deployment. The small subset of events that verbose logging adds should not be any cause for concern during normal operations. However, they may be useful in situations in which you are troubleshooting service issues. If for any reason verbose logging is reset to streamline logging, you can use the following command to reset AD FS 2.0 event logging to the verbose installation default setting:

Set-ADFSProperties  -LogLevel Verbose,Errors,Warnings,Information

Configure debug tracing for AD FS 2.0

Enabling debug tracing for AD FS 2.0 provides an extended set of events that can help you troubleshoot issues. AD FS 2.0 uses the Event Tracing for Windows (ETW) framework to log traces.

To enable debug tracing for AD FS 2.0, you use Event Viewer and you configure it to enable logging of events that have the AD FS 2.0 Tracing event source. Unlike the AD FS 2.0 event log, the AD FS 2.0 trace log is not enabled by default because hundreds of trace log entries can be logged each time that the Federation Service processes a request.

By default, the trace log file size is configured to be 10 gigabytes (GB) in size, and the log is not circular, which means it will recycle and overwrite older log file data with more recent log data. You can change trace log file properties by right-clicking the AD FS 2.0 Tracing\Debug node and selecting the Properties option in Event Viewer.

To enable verbose trace logging, stop AD FS 2.0 trace logging, run the following Wevutil.exe command-line, and then restart AD FS 2.0 trace logging:

wevtutil sl "AD FS 2.0 Tracing/Debug" /l:5

For more information about enabling debug tracing, see Enable Debug Tracing for AD FS 2.0 (https://go.microsoft.com/fwlink/?LinkId=182388).

WCF and WIF trace messages

Sometimes it may be necessary to look at Windows Communication Foundation (WCF) and Windows Identity Foundation (WIF) trace messages to troubleshoot an issue. AD FS 2.0 makes it possible for WCF and WIF traces to be logged in the AD FS 2.0 trace log along with AD FS 2.0 traces. Enabling WCF and WIF tracing involves modifying the Microsoft.IdentityServer.ServiceHost.Exe.Config file. To enable WCF and WIF trace messages, modify the corresponding trace sources as shown in the following example by setting the appropriate value for the switchValue attribute. After you apply these changes, save the configuration and restart the AD FS 2.0 Windows service to start with WCF and WIF trace messages in the AD FS 2.0 trace log.

<system.diagnostics>
<sources>
<!-- To enable WIF tracing, change the switchValue below to desired trace level - Verbose, Information, Warning, Error, Critical -->
<source name="Microsoft.IdentityModel" switchValue="Off"> … </source>
<!-- To enable WCF tracing, change the switchValue below to desired trace level - Verbose, Information, Warning, Error, Critical -->
<source name="System.ServiceModel" switchValue="Off" > … </source>
</sources>
</system.diagnostics>

When you enable the traces by setting the appropriate switches, WIF traces will appear in the AD FS 2.0 trace log under the keyword ADFSWIF and WCF traces appear in the trace log under the keyword ADFSWCF.

Correlating AD FS 2.0 events and traces using Activity ID and Caller ID

When an error occurs during processing of a single token-issuance request by the Federation Service, multiple errors might be logged by AD FS 2.0 and the federation passive Web application in the event log. In addition, there may be multiple errors logged that correspond to different token-issuance requests by different users. For these reasons, analyzing a particular request failure might be difficult because of the volume of events that can be present in the logs.

To assist in correlating AD FS 2.0 events in the event log that correspond to a particular request, the Federation Service generates an Activity ID, a globally unique identifier (GUID) that maps WCF and WIF events and trace messages to each specific token-issuance request that is processed.The Activity ID is logged as part of every event that AD FS 2.0 logs or traces. You can use the Activity ID to filter messages in the event log to help isolate and examine all events that correspond to a specific token-issuance request.

Debugging token issuance request failures using the Caller ID event

When you are able to locate the ActivityID attribute for cross-referencing AD FS 2.0 events with AD FS 2.0 trace log entries, you can use this attribute to debug token-issuance request failures for the Federation Service. The critical link for this is the Caller ID event, a special event that is logged during token-issuance failures in the AD FS 2.0 event log as a warning and with Event ID 1000. This event contains the claim type and value of possibly one of the following claim types, if they are available in the caller identity information that is passed to the Federation Service as part of a token request:

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

• https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

• https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn

• https://schemas.microsoft.com/ws/2008/06/identity/claims/upn

• https://schemas.xmlsoap.org/claims/UPN

• https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

• https://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress

• https://schemas.xmlsoap.org/claims/EmailAddress

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

• https://schemas.microsoft.com/ws/2008/06/identity/claims/name

• https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier

Note that the Caller ID event also has ActivityID logged (as described in the previous tip). By searching for specific claim values that correspond to these claim types, you can locate the Activity ID in the Caller ID event and use that Activity ID to filter or search the event log and trace log that correspond to all the events and traces for that request.

As an alternative, there is another way to obtain the Activity ID from users when a token issuance occurs in a browser-based application scenario. When a passive client Web application shows a generic error page with the error message for the failed token request, it also displays the Activity ID that corresponds to the failure as part of Additional data. The user who sees the error in the browser can send the Activity ID to support personnel, who then use this value to search the AD FS 2.0 event and AD FS 2.0 trace logs and locate all error events and traces (if tracing is enabled) that correspond to the token-issuance request that failed.

Filtering AD FS 2.0 events

You can use the following procedures to search and filter AD FS 2.0 event and trace log entries.

To search and find an Activity ID in AD FS 2.0 events

1. Open Event Viewer.

   To open Event Viewer, click Start, point to Programs, point to Administrative Tools, and then click Event Viewer.

2. In the console tree, expand Applications and Services Logs, expand AD FS 2.0, and then click AD FS 2.0/Admin.

3. On the Action menu, click Find, enter the Activity ID you are looking for, and then click Find Next to locate and view each event that is associated with the Activity ID that you entered.

To filter the AD FS 2.0 logs to display only events or traces that match a specific Activity ID

1. Open Event Viewer.

   To open Event Viewer, click Start, point to Programs, point to Administrative Tools, and then click Event Viewer.

2. In the console tree, expand Applications and Services Logs, expand AD FS 2.0, and then click AD FS 2.0/Admin.

3. On the Action menu, click Filter Current Log.

4. Click the XML tab, and then select the Edit query manually check box.

5. Click Yes when you are prompted to confirm manual editing of the query.

6. Update the query as shown in the following example to include the ActivityID attribute to set as the scope of the log filter (modify ActivityID in the example with the exact value of ActivityID from your deployment), and then click OK.

   <QueryList>
     <Query Id="0" Path="AD FS 2.0 Eventing/Admin">
       <Select Path=" AD FS 2.0/Admin ">*[System[Correlation[@ActivityID='{ 77269359-0b7d-45cb-9760-e3a4009883d9}']]]</Select>
     </Query>
   </QueryList>
   

Configure auditing for AD FS 2.0

Enabling auditing for AD FS 2.0 might be beneficial in situations in which you place a high value on the security of your identity deployment and prefer to monitor it closely for suspicious or unintended activity. The value of auditing might be balanced by the increased time that you spend reviewing or managing the additional event log detail that auditing can generate in your deployment.

The process of enabling auditing for AD FS 2.0 requires changes that you make using the Local Security Policy snap-in for your federation server as well as changes in the Service properties that you set using the AD FS 2.0 Management console.

To enable auditing for AD FS 2.0

1. Click Start, point to Programs, point to Administrative Tools, and then click Local Security Policy.

2. Navigate to the Security Settings\Local Policies\User Rights Management folder, and then double-click Generate security audits.

3. On the Local Security Setting tab, verify that the AD FS 2.0 service account is listed. If it is not present, click Add User or Group and add it to the list, and then click OK.

4. Open a command prompt with elevated privileges and run the following command to enable auditing.

   auditpol.exe /set /subcategory:"Application Generated" /failure:enable /success:enable
   

5. Close Local Security Policy, and then open the AD FS 2.0 Management snap-in.

   To open the AD FS 2.0 Management snap-in, click Start, point to Programs, point to Administrative Tools, and then click AD FS 2.0 Management.

6. In the Actions pane, click Edit Federation Service Properties.

7. In the Federation Service Properties dialog box, click the Events tab.

8. Select the Success audits and Failure audits check boxes.

9. Click OK.

To disable auditing AD FS 2.0

1. Open a command prompt with elevated privileges and run the following command to enable auditing.

   auditpol.exe /set /subcategory:"Application Generated" /failure:disable /success:disable
   

To verify the status for AD FS 2.0 auditing

1. To verify the current status of auditing for AD FS 2.0 you can run the following command:

   auditpol.exe /get /subcategory:"Application Generated" /r
   

Configure performance monitoring for AD FS 2.0

AD FS 2.0 includes its own dedicated performance counters. To use the Windows Reliability and Performance Monitor to monitor the performance of your AD FS 2.0 servers, you can create a new data collector set and add the AD FS 2.0 counters to that view. For more information about setting up performance monitoring for AD FS 2.0, see the AD FS 2.0 Deployment Guide (https://go.microsoft.com/fwlink/?LinkID=181110).