Federation Guides › Partnership Federation Guide › Log Files which Aid Troubleshooting

Log Files which Aid Troubleshooting

This section contains the following topics:

Federation Web Services Trace Logging

Log Messages for the Fed_Server Component

Configure FWS Trace Logging

Resolving Signature Verification Failures

Simplify Logging with Trace Configuration Templates

Update FWS Data in the Logs

Federation Database Objects Trace

Federation Web Services Trace Logging

The Web Agent trace logging facility and the Policy Server Profiler monitor the performance of the Web Agent and Policy Server. These logging mechanisms provide comprehensive information about SiteMinder operation so you can analyze the system performance and can troubleshoot issues.

For partnership federation, several logging components are available to collect trace messages for federated communication. Trace messages provide detailed information about system operation. Trace messages are ordinarily turned off during normal operation. You can enable them to extract in-depth information in addition to the trace message itself. For example, you can look at the fwstrace.log to see the generated SAML assertion or collect the name of the current user.

The collected trace messages are written to a trace log. The fwstrace.log is located in the directory web_agent_home/log.

You can establish trace logs at the Web Agent and the Policy Server to monitor SiteMinder operation.

Log Messages for the Fed_Server Component

The component that controls the trace messages for federation services at the Policy Server is the Fed_Server component. This component monitors activity for the assertion generator and the SAML authentication scheme. For example, you can view the generated assertion in the smtracedefault.log file.

To configure logging at the Policy Server, use the Policy Server Profiler. The Profiler lets you specify components for trace logging, which include.

For more information about using the profiler, see the SiteMinder Policy Server Administration Guide.

Federation Services Trace Logging (smtracedefault.log)

The profiler is the Policy Server facility for logging. You can use the profiler to collect trace messages for federation services and write them to the smtracedefault.log file.

The component that controls the trace messages for federation services at the Policy Server is the Fed_Server component.

The Policy Server Profiler allows you to trace internal Policy Server diagnostics and processing functions.

Follow these steps:

1. Start the Policy Server Management Console.

   Important! If you are accessing this graphical user interface on Windows Server 2008, open the shortcut with Administrator permissions. Use Administrator permissions even if you are logged in to the system as an Administrator. For more information, see the release notes for your SiteMinder component.

2. Click the Profiler tab.
3. Set the Enable Profiling option to enable profiling.
4. To select configuration settings for the Profiler, do one of the following:
   • Accept the Profiler settings specified by the default smtracedefault.txt file presented in the Configuration File drop-down list.
   • Select another configuration file that has already been selected during this management session from the Configuration File drop-down list.
   • Click the Browse button to select another configuration file.
5. To change the Profiler settings stored in a Profiler configuration file and save them in the same or a new file, click the Configure Settings button to open the Policy Server Profiler dialog.
6. Adjust the settings presented in the Output group box to specify the output format for information generated by the Policy Server Profiler.
7. Click Apply to save your changes.

Notes:

Changes to the Profiler settings take effect automatically. However, if you restart the Policy Server, a new output file (if the Profiler is configured for file output) is created. The existing Profiler output file is automatically saved with a version number. For example:

smtracedefault.log.1

If changes to the Logging or Tracing facility settings are not related to the Profiler output file, for example, enabling/disabling the console logging on Windows, the existing file is appended with new output without saving a version of the file.

By default The Policy Server retains up to ten output files (the current file and nine backup files). Older files are replaced automatically with newer files when the ten file limit is reached. You can change the number of files to retain by configuring the TraceFilesToKeep DWORD registry setting to the required decimal value. The TraceFilesToKeep registry setting must be created in the following registry location:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Netegrity\SiteMinder\CurrentVersion\
LogConfig\TraceFilesToKeep

The Profiler tab has a "Buffered Tracing" option, which is set by default to improve Policy Server performance. This option is on Solaris systems only.

Configure FWS Trace Logging

To collect trace messages for the Federation Web Services application, configure the FWS trace logging.

Follow these steps:

1. Do one of the following tasks:
   • Make a copy of the default template, FWSTrace.conf and modify the file to include only the data you want to monitor.
   • Copy one of the preconfigured templates and assign a new name to it.

   Note: Do not edit the template directly.

2. Open the LoggerConfig.properties file in the directory web_agent_home/affwebservices/WEB-INF/classes, and set the following parameters:
   • Set TracingOn to Yes. This option instructs the trace facility to write messages to a file.
   • Set the TraceFileName parameter to the full path of the trace log file. The default location is in web_agent_home/config/FWSTrace.log.
   • Set the TraceConfigFile parameter to the full path of the trace configuration file, either the default template, FWSTrace.conf or another template. Templates can be found at web_agent_home/config.
3. Optionally, you can format the trace log file, the file that contains the log output. The following parameters are the Web Agent configuration parameters that dictate the format of the trace log file:
   • TraceRollover
   • TraceSize
   • TraceCount
   • TraceFormat
   • TraceDelim

   The LoggerConfig.properties file contains descriptions of all these settings.

Resolving Signature Verification Failures

A malicious user can commit an XML signature wrapping attack by changing the content of a document without invalidating the signature. By default, software controls for the Policy Server and Web Agent Option Pack are set to defend against signature wrapping attacks. However, a third-party product can issue an XML document in a way that does not conform to XML specifications. As a result, the default signature checks can result in a signature verification failure.

Signature verification failures occur for the following reasons:

• A duplicate ID element is in the XML document and the signature references this duplicate ID. Duplicate ID attributes are not permitted.
• The XML signature does not reference the expected parent element, and a signature wrapping vulnerability is logged.

If a federation transaction fails, examine the smtracedefault.log file and the fwstrace.log file for a signature verification failure. These errors can indicate that the received XML document is not conforming to XML standards. As a workaround, you can disable the default Policy Server and Web Agent protection against signature wrapping attacks.

Important! If you disable the protection against signature vulnerabilities, determine another way to protect against these attacks.

To disable the XML signature wrapping checks:

1. Navigate to the xsw.properties file. The file exists in different locations for the Policy Server and the Web Agent.
   • For error messages in the Policy Server smtracedefault.log file, go to siteminder_home/config/properties
   • For error messages in the Web Agent fwstrace.log, go to

     web_agent_option_pack_ home/affwebservices/web-INF/classes.

     Note: If the web agent option pack is installed on the same system as the web agent, the file resides in the web_agent_home directory.

2. Change the following xsw.properties settings to true:
   • DisableXSWCheck=true (Policy Server setting only)
   • DisableUniqueIDCheck=true (Policy Server and Web Agent Option Pack setting)

     Note: The value of the DisableUniqueIDCheck setting must be the same for the Policy Server and the Web Agent Option Pack.

3. Save the file.

Simplify Logging with Trace Configuration Templates

To make the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Policy Server and the Web Agent Option Pack. You can use these templates instead of creating your own trace configuration file to collect the data that gets written to a trace log.

Trace Logging Templates for the IdP and SP

To make the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Policy Server. You can use these templates instead of creating your own trace configuration file to collect the data that gets written to a trace log.

The following templates are available for trace logging related to the Identity Provider and the Service Provider, such as assertion generation or SAML authentication.

Look at each template to see the exact contents. The templates are located in siteminder_home/config/profiler_templates.

Service Provider Template Sample

The following text is the samlsp_trace.template file.

components: Server/Policy_Server_General, IsProtected/Resource_Protection, Login_Logout/Authentication, Login_Logout/Policy_Evaluation, Login_Logout/Active_Expression, Login_Logout/Session_Management, IsAuthorized/Policy_Evaluation, JavaAPI, Fed_Server/Auth_Scheme, Fed_Server/Configuration
data: Date, Time, Tid, TransactionID, SrcFile, Function, Domain, Resource, Action, User, Message

For legacy federation, it includes the Fed_Server component along with the subcomponents Auth_Scheme and Configuration.

The data fields that indicate the required contents of each message are:

Date, Time, Tid, TransactionId, SrcFile, Function, Domain, Resource, Action User, and Message.

Identity Provider Profiler Sample

At the Identity Provider, the Profiler tab of the Policy Server Management Console specifies a template in the Configuration File field. The following text is a sample entry for the Configuration File field:

c:\program files\ca\siteminder\config\profile_templates\samlidp_template.trace

For more information about using the Profiler, see the Policy Server Administration Guide.

Federation Web Services Trace Logging (FWSTrace.log)

To simplify the task of collecting tracing data simpler, a series of preconfigured templates are installed with the Web Agent Option Pack. You can use these templates instead of creating your own trace configuration file to collect the data.

The following templates are available:

All the FWS templates include the Fed_Client component and subcomponents for the specific data being tracked. To see the exact contents, open each template.

Follow these steps:

1. Navigate to the template directory in web_agent or web_agent_option_pack_home/config.
2. Make a copy of the template, rename it.
3. (Optional) Modify the template so it includes only the data you want to monitor.

   Note: Do not edit the template directly.

4. Save the new template.

The templates determine the federation components that the federation system monitors. To enable trace logging and format how the data appears in the log file, modify the Logger.Config properties file.

Follow these steps:

1. Navigate to web_agent or webagent_optionpack_home/affwebservices/WEB-INF/classes.
2. Open the LoggerConfig.properties file. The LoggerConfig.properties file contains descriptions of all the settings.
3. Set the TracingOn setting to Yes. This option instructs the trace facility to write messages to the log file.
4. Set the TraceFileName setting to the full path of the log file. The default location is in web_agent or webagent_optionpack_home/config/FWSTrace.log.

   Note: You can rename the log file. FWSTrace.log is the default name.

5. Set the TraceConfigFile setting to the full path of the trace configuration file. This file can be the default template, one of the other preconfigured templates, or your own configuration file. Regardless of which template you specify, all output is written to the log file you specify in the TraceFileName setting.

   Specify only one template. All the templates reside in the directory web_agent or web_agent_option_pack_home/config.

6. Optionally, modify how the information in the trace log output file is displayed. The following settings dictate the format of the log file:
   • TraceRollover
   • TraceSize
   • TraceCount
   • TraceFormat
   • TraceDelim

FWS Template Sample

The following text is an excerpt from the FWS_SLOTrace.conf template. Most of the file contains comments and instructions on how to use the file, the command syntax, and the available subcomponents for the Fed_Client component.

The excerpt shows the component, Fed_Client and the subcomponents (Single_Logout and Configuration) that are monitored. The excerpt also shows the specific data fields that indicate the required contents of each message (Date, Time, Pid, Tid, TransactionId, SrcFile, Function, Message).

components: Fed_Client/Single_Logout, Fed_Client/Configuration
data: Date, Time, Pid, Tid, TransactionID, SrcFile, Function, Message

Update FWS Data in the Logs

If you modify any part of the federation configuration, flush the Federation Web Services cache for the changes to appear in the trace logs.

Note: A brief delay can occur from when the changes are made and when Federation Web Services receives the information.

To flush the cache

1. Log in to the Administrative UI.
2. Select Administration, Policy Server, Cache Management.

   The Cache Management page displays.

3. Click Flush All in the All Caches section of the page.
4. Click Close

Federation Database Objects Trace

Enable XPS validation and federation object tracing to monitor federation database activities. SiteMinder logs these activities to the smps.log file, in the directory siteminder_home\log.

Follow these steps:

1. Open a command window.
2. Type XPSConfig.

   Type the command as it is shown here. The command is case-sensitive.

   The Products Menu displays.

3. Enter XPS.

   The Parameters Menu displays.

4. Enter the number for the LogValidationWarnings parameter.
5. Enter c to change the value to true. With a Boolean value, XPSConfig automatically changes the value to the opposite of the current setting.

   When set to true, the parameter enables tracing for XPS Validation warnings.

6. Enter the number for the Trace parameter.
7. Enter c to change the value to true.

   When set to true, the parameter enables XPS trace debugging.

8. Enter q until you return to the Product Menu.
9. Enter FED.

   The FED parameters menu display.

10. Enter the number for the TRACE parameter.
11. Enter c to enable it.

    When set to true, the TRACE parameter enables tracing for federation XPS objects.

12. Enter q to return to the Parameters Menu. If you are done modifying parameters, keep entering q until you exit XPSConfig.

    Changes made in XPSConfig are not recognized until you exit the XPSConfig tool. Where noted, some changes require that you restart services.

13. Restart the Policy Server.