Previous Topic: Federation Web Services URLs Used by SiteMinderNext Topic: Creating a Legacy Federation Configuration in the Partnership Model


Troubleshooting

This section contains the following topics:

Transaction IDs to Aid Federation Troubleshooting

General Issues

SAML 1.x-Only Issues

SAML 2.0-Only Issues

Transaction IDs to Aid Federation Troubleshooting

Troubleshooting a federated transaction is difficult when many transactions are logged in one file. To follow a single transaction in a trace log, use the SAML transaction ID. When a federation call occurs, the FWS application first generates a SAML Transaction ID. The SAML Transaction ID is generated only once. This unique SAML transaction ID can map to multiple transaction IDs

For example, you can see the following message in the fwstrace.log for a SAML 2.0 POST transaction. Note the line in bold that shows the mapping of the two transaction IDs.

[08/01/2013][17:33:54][2292][1884][1c2d7650-b006e46a-ed071f41-bbbede33-fe78e2dd-38d][SSO.java][processAuthentication][SAMLTransactionID 2aaf90ec-fdef4897-0ef49d91-63d4031d-f508a3e9-12 maps to TransactionID: 1c2d7650-b006e46a-ed071f41-bbbede33-fe78e2dd-38d.]

The CA SiteMinder® Federation system generates a new SAMLTransactionID only if it is acting as the asserting party. These specific activities are:

At the relying party, there exists a request ID, which can be traced easily through the log files. The request ID makes it unnecessary for the CA SiteMinder® Federation system to generate a SAMLTransactionID at the relying party.

For each unique SAML transaction ID, there can be multiple transaction IDs. When a new HTTP transaction occurs, a new transaction ID is generated. This transaction ID is mapped to the single SAML transaction ID. For example, in the trace log you can see the following entries:

SamlTransactionID ["xyz"] maps to TransationID["123"]
["123"] HTTP operation
["123"] HTTP operation

A new transaction ID "456" is generated:

SamlTransactionID["xyz"] Maps to Transactionid["456"]
["456"] <some operation>
["456"] <some operation>

Transaction IDs are placed in the fwstrace.log and the smtracedefault.log. The same set of transaction IDs for a single transaction is written to each of these logs. The trail of IDs in these logs enables you to follow a transaction. If there is a failure, the IDs help you determine which event failed for a transaction.

General Issues

The following troubleshooting topics apply to SAML 1.x and SAML 2.0.

Web Agent Option Pack Fails to Initialize Due to Invalid smjavaagent.dll

Symptom:

The Web Agent Option Pack fails to initialize with on a system with other CA products. Error messages, such as "Java Agent API initialization FAILED" or "unsatisfied link error" display.

Error messages similar to the following appear in the Federation Web Service log file:

11:04:46 AM[29959477:E] Exception while reading the WebAgent configuration information: javaagent_api_getConfig
11:04:46 AM[29959477:E] Java Agent API initialization FAILED.

Solution:

An invalid version of smjavaagentapi.dll can be present the system path. Verify that all installed products are compatible with one another and of compatible versions.

To verify the versions

  1. Log in to the Technical Support site.
  2. Search for the CA SiteMinder® Platform Support Matrix for 12.52.
Cookie Domain Mismatch Errors

Symptom:

After successful SAML authentication at consumer/SP site, the consumer/SP Web Agent still challenges the user because of cookie domain mismatch.

Solution:

Verify that the producer/IdP and consumer/SP are not in the same cookie domain. Legacy federation does not support federation within the same cookie domain. Separate cookie domains are required at the producer/IdP and consumer/SP sites. Additionally, verify that the CookieDomainScope parameter is set to the appropriate value for your environment. This parameter is a Web Agent parameter (see information about single sign-on in the CA SiteMinder® Web Agent Configuration Guide.

If separate cookie domains are in use, verify that the cookie domain in the Agent configuration matches the domain name in the requested target URL.

Error After Successful Authentication at Consumer/SP

Symptom:

After successful authentication at the consumer site, an HTTP 404 "Page Not Found" error code is returned to the browser.

Solution:

Verify that the target page exists in the web server document root. Examine the FWS trace log to verify that the user is being redirected to the correct URL.

HTTP 404 Error When Trying to Retrieve Assertion at the Consumer

Symptom:

When the relying party tries to retrieve an assertion, an HTTP 404 "Page Not Found" error code is returned to the browser.

Solution:

Verify that the Federation Web Services application is deployed as a web application. Deploy the application on a web server running one of the supported application servers. The CA SiteMinder® Platform Support Matrix lists the supported platforms for the Web Agent Option Pack.

More Information:

Deploy Federation Web Services as a Web Application

Federation Web Services Fails to Send SAML Request to Producer/IdP

Symptom:

The Federation Web Services application at the consumer/SP fails to send a SAML request message to the producer/IdP. The consuming side fails to trust the certificate of the web server.

Solution:

Add the certificate of the Certificate Authority that issued the client certificate to the key database of the web server at the producer/IdP.

Matching Parameter Case-Sensitivity Configuration Issues

Symptom:

Problems occur due to conflicts between configuration parameters that must correspond on producer/Identity Provider and consumer/Service Provider, even though the parameters appear to match.

Solution:

The URL string that comes after the colon is case-sensitive. For example, the text after http: is case-sensitive. Therefore, the case of the URLs in all corresponding settings must match.

Parameter values that must match between the asserting and relying parties are documented in the topic Configuration Settings that Must Use the Same Values.

Policy Server System Fails After Logoff

Symptom:

In some environments, logging off the Policy Server while it is running causes the Policy Server to fail. The failure is due to a JVM issue.

Solution:

Add the -Xrs command to its own command line in the JVMOptions.txt file. This command is case-sensitive, so add it as shown. This command reduces usage of operating system signals by the JVM.

The JVMOptions.txt file is located in policy_server_home/config/.

Multibyte Characters in Assertions are Not Handled Properly

Symptom:

When you include a multibyte character in an assertion, problems can occur.

Solution:

Set the LANG setting for your operating system to UTF-8, as follows:

LANG=xx_xx.UTF-8

For example, for Japanese, the entry would be:

LANG=ja_JP.UTF-8

Trace Logs Not Appearing for IIS Web Server Using ServletExec

Symptom:

You have enabled trace logging in the LoggerConfig.properties file, but the affwebservices.log and FWStrace.log files are not being written to the WEB-INF/classes directory.

Solution:

Verifies that the anonymous user account associated with ServletExec has permissions to write to the Windows file system. If the user account does not have the right to act as part of the operating system, ServletExec cannot write the log files.

More information:

Enable ServletExec to Write to the IIS File System

Error During Initialization of JVM

Symptom:

If you receive the following error message in the Policy Server log (figure out which log):

Error occurred during initialization of JVM
Could not reserve enough space for object heap.

The Web Agent Option Pack functionality is not working due to a JVM initialization failure.

Solution:

Restrict the object heap memory size.

To restrict the memory size

  1. Open the JVMOptions.txt file, in the directory web_agent_home/WEB-INF/properties file.
  2. Add the following entry to the file as it is written here:
    -Xms128M
    
  3. Save the file.
  4. Restart the Policy Server.

SAML 1.x-Only Issues

The following issues apply only to SAML 1.x features.

SAML 1.x Artifact Profile Single Sign-On Failing

Symptom:

If single sign-on with the SAML 1.x artifact profile is configured, the consumer site fails to send SAML request messages to the producer. Error messages similar to the following appear in the Federation Web Service log file:

May 23, 2012 4:20:44.234 PM[28349544:E] Dispatcher object thrown unknown exception while processing the request message. Message: java.net.ConnectException: Connection refused: connect.
May 23, 2012 4:20:44.234 PM[28349544:E] Exception caught. Message: com.netegrity.affiliateminder.webservices.m: Exception occurred while message dispatcher(srca) object trying to send SOAP request message to the SAML producer.

Solution:

Verify that the web server hosting the Assertion Retrieval Service is running with a configured SSL port.

Failed Authentication for Access to Assertion Retrieval Service

Symptom:

In an environment using SAML 1.x artifact single sign-on, the consumer fails authentication when trying to access the Assertion Retrieval Service at the producer.

Solution:

If basic authentication protects the Assertion Retrieval Service, verify the Name and Password for the Affiliate configuration match the Affiliate Name and Password for the SAML Artifact authentication scheme.

Authentication Fails After Modifying Authentication Method

Symptom:

If you change the authentication method protecting the SAML 1.x Assertion Retrieval Service from Basic to Client Cert, subsequent authentication requests can fail.

If you change the authentication method protecting the SAML 1.x Assertion Retrieval Service from Client Cert to Basic, subsequent authentication requests can fail.

Solution:

Restart the web server after the authentication method is changed.

Client Authentication Fails for SAML Artifact Single Sign-on

Symptom:

Client certificate authentication for SAML 1.x artifact single sign-on fails at the producer. The following error is logged in the web agent trace logs:

Setting HTTP response variable HTTP_consumer_name=from SiteMinder

For example, if the Attribute Name in the response is configured as "name" for an LDAP User Directory, the response fails.

Solution:

Verify that you create a Web Agent response under the domain FederationWebServicesDomain. The response must be as follows:

Attribute type

WebAgent HTTP Header variable

Attribute Kind

User Attribute

Variable Name

consumer_name

Attribute Name

uid (for LDAP) or name (for ODBC)

SAML 2.0-Only Issues

The following issues apply only to SAML 2.0 features.

Failed Authentication to Access the Assertion Retrieval Service

Symptom:

If you configure SAML 2.0 artifact single sign-on, the Service Provider fails to authenticate when accessing the Artifact Resolution Service at the Identity Provider.

Error messages similar to the following appear in the Federation Web Service log file:

May 23, 2005 4:43:51.479 PM[31538514:E] SAML producer returned error http status code. HTTP return status: 401. Message: <HTML><HEAD><TITLE>401: Access Denied</TITLE></HEAD><BODY><H1>401: Access Denied</H1>
Proper authorization is required for this area. Either your browser does not perform authorization, or your authorization has failed.</BODY></HTML>

Solution:

Depends upon the configured authentication:

ODBC Errors Deleting Expiry Data From Session Store

Symptom:

If you upgrade a Policy Server from an earlier version, ODBC errors can occur when deleting expiry data from the session store.

Solution:

Upgrade the session store schema as described in the CA SiteMinder® Upgrade Guide.