Custom Error Handling For Applications

Web Agent Guides › Web Agent Configuration Guide › Web Application Protection › CA SiteMinder® Default HTTP Headers › Custom Error Handling For Applications

Custom Error Handling For Applications

Custom error handling allows you to make error information relevant to your application. To customize applications for users, you can add the HTML text displayed by HTTP 500, HTTP 401, and HTTP 403 error pages or, with the exception of 401 errors, you can redirect the user to a URL that points to a custom error page or application.

You can configure customized handling for the following types of errors:

Server errors—the Agent uses the ServerErrorFile for error pages that result from HTTP 500 web server errors. These error codes are passed to the custom error pages and include:
- Problems because the Web Agent cannot read values from required HTTP headers.
- Advanced authentication cookies cannot be parsed or contain an error status.
- Connectivity problems between the Web Agent and the Policy Server.
Access Denied errors—the Agent uses the file specified in the following parameter:

Custom401ErrorFile

Specifies the customized HTML page to display when users receive a 401 (insufficient privileges) browser error. These errors occur when a user does not have the appropriate privileges to access a resource.

Note: Some web servers append text of their own to the custom text that you choose. So the response pages for these servers are not customizable.

Default: No default (blank).
Require cookies errors—if the RequireCookies parameter is set, the Web Agent sets a cookie during basic authentication. If this cookie is not returned by the browser with the basic credentials, the error page designated by the ReqCookieErrorFile parameter is returned, and the Agent denies the user access to the web server.
Cross-site scripting errors—the Agent uses the file specified in the CSSErrorFile parameter for error pages that result from HTTP 403 cross-site scripting errors. Cross-site scripting can compromise the security of a Web site.

After you create these HTML files or applications, direct the Web Agent to the custom error pages or URLs.

Note: For an Apache server being used as a proxy or reverse proxy server, the Apache Agent will not return custom CA SiteMinder® error pages, but will return the standard Apache HTTP 500 and 403 error pages.

How to Set Up Error Handling

To customize how your applications display error messages for users, do any of the following tasks:

Add HTML text that the browser displays for the following HTTP errors:
- 500
- 401
- 403
Redirect the user to a URL that points to a custom error page or application.

For HTTP 500 and 403 errors only: If you configure the agent to redirect the user to a URL, the agent appends the error code to the URL. See the following example of an appended URL:

?SMError=error_code,

If you add standard HTML error text, you can only specify HTML code between the following tags:

<body> 
</body>

To direct the agent to the custom error pages or URLs, do one of the following tasks:

Specify the path where the text files reside.

Enter the URL in the value of the respective agent configuration parameter.

Errors and other events and the respective agent configuration parameters are listed in the following table:

Set a custom response for this type of error:	With the value of this configuration parameter:
Server errors	ServerErrorFile
Access denied errors	Custom401ErrorFile
Cookie required errors	ReqCookieErrorFile
CSS characters errors	CSSErrorFile

The error files can reside anywhere in your application.

Important! Leave any URL you configure as a custom error page unprotected.

Note: If the URLs of your applications require HTML tags, encode the characters in the tags. For information about encoding HTML characters, see: http://www.cert.org/tech_tips/.

The following examples show a file path and a URL to an error file. The syntax in the example is for a local configuration file. You can also set these parameters in an agent configuration object.

File Path:

CSSErrorFile="C:\error\error.txt"

ReqCookieErrorFile="C:\custompages\error.txt"

ServerErrorFile="C:\error\error.txt"

Custom401ErrorFile="C:\error\accessdenied.txt"

URL:

CSSErrorFile="http://www.mycompany.com/error.jsp"

ReqCookieErrorFile="http://www.myorg.com/error.asp"

ServerErrorFile="http://www.mycompany.com/error.jsp"

More Information

Custom Error Handling For Applications

Notes for Custom 401 Pages

Do not set the Custom401errorfile parameter to a URL.
If a value (usable or not) for Custom401errorfile exists, the Agent will check every 60 seconds to see if the file has changed. However, the response is intended to be static in nature. You cannot, for example, insert a "user_name denied" type of dynamic message.
Because re-checking is triggered by the existence of the Custom401errorfile value rather than its usability, you can correct an error without restarting the agent. The correction will be picked up on the next check.
The customized message file text will not be exposed by other errors. The file pathname will be logged at startup and in the case of error.
The extent of customization may be limited by the web server, which may add text of its own to the response.
The size of the customized text file is limited only by the system file size limit.