Advanced Password Services (APS) Guide › Troubleshooting

Troubleshooting

Many things can happen when APS is not properly configured. A few of the more common issues are described below.

In all cases, the first thing that should be examined is SiteMinder’s Authentication Service Console Log on the Policy Server. APS records all significant activity into this log. If something is happening that you suspect should not be happening, always check this log first.

Always make sure that you have applied all of the latest patches/service packs to your APS installation. Often, a given problem has already been found at another site and fixed in a patch. Patches are available for download from the Netegrity support site.

If you still cannot resolve the issue, open a case using Netegrity’s support Web Site. In order to optimize response time from Netegrity, be sure to do the following:

Make sure that the case clearly identifies the issue as an APS issue (both in the text and as the product/component).
Make sure to identify the correct versions of APS, SiteMinder and your Operating System platform(s).
Attach your entire APS.cfg and SmPortal.cfg files to the case.
Attach a complete copy of the SiteMinder Authentication Service Console Log to the case. Please do not just cut/paste important lines, sometimes the issue requires that we see the entire authentication process.
A site can request that additional information (traces) be written to this log. To do so, set the "Trace" keyword in the APS Configuration File. To turn off this tracing, delete the "Trace" keyword.

In APS Version 4.0, all of the entries placed into the Authentication Log were reviewed and their format standardized. Each specifically identifies its source as APS. Please note that it would be impossible to document the information logged, since it changes from release to release.
Be sure to properly prioritize your case. The rules of thumb are:
1. Priority ONE is reserved for PRODUCTION SERVER OUTAGES ONLY and require immediate attention.
2. Priority TWO is for serious outages that will impact rollouts, are holding up development or testing efforts, or are considerable inconveniences in production (such as requiring frequent server restarts, etc).
3. Priority THREE is for all other issues.
4. Capabilities questions (such as "Can APS do this…?") should be directed to your sales engineer or sales representative, rather than logged to our support site.
Unfortunately, a few customers have been known to overstate the priority of their cases intentionally, in an effort to get more immediate response.

Rather than being productive, this has two adverse effects:
- It will cause the resolution of other customers’ issues to be delayed as we deal with the higher priority case. Please be consciencious to other customers.
- Support becomes aware, over time, of customers that overstate priorities. After awhile, such priorities may not be taken as seriously as they should be, since Support may not be able to differentiate

This section contains the following topics:

Connectivity Problems

Various APS components communicate with the Policy Server via SmPortal/SmTransact. This is the troubleshooting section for those connectivity issues.

This kit provides a comprehensive set of error codes that can be used to determine and resolve problems with services.

These errors are distinct from application errors and should not be confused with them. The errors displayed by SmPortalTest are all tunnel errors and that makes SmPortalTest a good tool for validating configuration.

A zero error return indicates success (though the service itself may have failed and thus returned a non-zero application error).

Negative numbers indicate client side (SmPortal) errors. These errors typically indicate an invalid configuration.

Positive errors indicate an error that occurred on the Policy Server when SmTransact attempted to execute the Service Provider (back-end) code. These are typically errors in service code.

A typical problem is that either multiple copies of SmPortal.cfg exist or that it does not exist on the same directory with SmPortal.dll. Only a copy on the same directory with SmPortal.dll will ever be used. Be careful of multiple copies of SmPortal.dll, because then it is difficult to determine which copy Windows elected to use.

Client Side (SmPortal) Errors

AGENT_FAILURE(-1)

This is, by far, the most frequent error encountered. It indicates that the SiteMinder Policy Server could either not be contacted (rare) or that the Policy Server refused the connection (very common). This is caused by either the agent not being defined on the Policy Server or a mismatch on the shared secret.

The best way to troubleshoot this error is to examine the SiteMinder console log (usually of the Authentication service), looking for entries denying a connection by an agent. The messages there are often cryptic, so check carefully the definition of the agent, especially the name of the agent (it is case-sensitive) and its shared secret.

This error should be considered equivalent to error -17, described below. Different versions of the SiteMinder Agent API return different errors, so you might see either error.

NOT_IMPLEMENTED (-11)

The application requested a function that is not currently implemented in SmPortal. This generally means that the service either requires a later version of SmPortal or that there is a significant problem with the application. Contact your application (or API) developer for resolution.

ERROR (-12)

This error indicates that a fault was detected during processing. This generally indicates a programming error.

ACCESS_DENIED (-13)

Indicates that the application program is not authorized to call into the Portal. This indicates a programming error in the application or API. Contact your application (or API) developer for resolution.

NO_AGENT (-14)

This error indicates that the Agent entry specified for the service could not be located in SmPortal.cfg. Check to make sure that the agent configured for this service is defined in the file.

NO_SECRET (-15)

SmPortal was unable to determine the shared secret for the specified agent. Check to ensure that a secret is defined for this service's agent.

NO_SERVERS (-16)

This error indicates that there are no servers defined for this agent in the SmPortal.cfg file.

AGENT_INIT (-17)

This error indicates that the SiteMinder Agent API could not be initialized. Typically, this error is returned if:

The server could not be found at the specified IP address;
The wrong port is configured for the server;
The agent name is undefined on that SiteMinder Policy Server;
The agent defined on the SiteMinder Policy Server should not be coming from that IP address;
The shared secret is wrong.

The Agent API intentionally does not distinguish between these errors. To do so would make cracking security significantly easier. To determine which of these cases is the actual cause, examine the Authentication Server's console log (on the Policy Server).

NO_SERVER_IP (-18)

This error indicates that one of the servers defined for the agent was not defined elsewhere in the SmPortal.cfg file. Make sure that all of the servers defined for the Agent are defined with, minimally, an IP address (and that the IP address is not blank).

INVALID_CALL_HANDLE (-19)

This is an internal application error indicating that the application passed an invalid handle to the SmPortal API. This indicates a programming error in the application or API. Contact your application (or API) developer for resolution.

NO_DYNAMIC_LIBRARY (-20)

The dynamic library (SmPortal.dll on Windows NT, libSmPortal.so on Solaris) could not be located. Update your PATH (Windows) or LD_LIBRARY_PATH (Solaris) environment variable in the context of the running user so that the dynamic library can be found. This error may also occur if the library can be located, but cannot be loaded because of another dependency.

NO_CONFIGURATION (-21)

The SmPortal configuration file (usually SmPortal.cfg) could not be located or opened. This usually means that the file either doesn't exist, is in the wrong place, or there is a missing or improperly set environment variable.

Server Side (SmTransact) Errors

All of these errors indicate a problem on the Policy Server.

INPUT_TOO_SMALL (1)

This error occurs when attempting to communicate with SmTransact without using SmPortal. It should never occur under normal circumstances.

NO_SERVICE (2)

This error occurs when attempting to communicate with SmTransact without using SmPortal. It should never occur under normal circumstances.