Web Agent Guides › Web Agent Configuration Guide › Protecting Web Applications › Define HTTPS Ports

Define HTTPS Ports

If you are using an SSL connection to the web server (HTTPS) to keep your requests more secure, specify the HTTPS port numbers with the following parameter:

HttpsPorts

Specifies the secure ports the Web Agent listens on if you are using an SSL connection to the web server. If you specify a value for this parameter, you must include all the ports for all the web servers that serve secure requests. If you do not specify a value, the Web Agent reads the HTTP scheme from the web server's context.

If a server is behind an HTTPS accelerator (which converts HTTPS to HTTP), the requests are treated as SSL connections by your browser.

Default: Empty

Example: 443

Example: (multiple ports) 443,7002

To define your HTTPS ports, set the value of the HttpsPorts parameter to the port numbers that use SSL. Use commas to separate multiple port numbers.

Use the HttpsPorts Parameter on Apache 2.x Servers

If you use an SSL accelerator or any intermediate device that changes the value of the HTTP_HOST header with an Apache 2.x Web server and use the HttpsPorts parameter, additional web server configuration changes are required.

Follow these steps:

1. Open the httpd.conf file of your Apache Web server, and then make the following changes:
   • Change the value of the UseCanonicalName parameter to on.
   • Change the value of the ServerName parameter to the following:

     server_name:port_number
     

     server_name

     Specifies the host name of the SSL accelerator.

2. Modify the following configuration parameter for your Web Agent:
   • Change the value of the GetPortFromHeaders parameter to yes.

Handle Multiple AuthTrans Functions for Oracle iPlanet Web Servers

AuthTrans functions are directives that initialize the Oracle iPlanet web server. The Oracle iPlanet web server executes AuthTrans functions in the order that they are listed in the obj.conf file. The Oracle iPlanet server reads through the AuthTrans functions until it finds a function that returns a REQ_PROCEED command. Once a REQ_PROCEED command executes, no other AuthTrans functions are executed.

By default, SiteMinder is the first AuthTrans function and it returns a REQ_PROCEED. To allow other AuthTrans functions to execute, you need to add the EnableOtherAuthTrans parameter and set the value to yes.

The default value for this parameter is no. To enable multiple AuthTrans functions set the EnableOtherAuthTrans parameter to yes.

By adding this parameter, you permit the SiteMinder Web Agent to exist with other functions.

Be sure the SiteMinder Agent function is the first entry in the obj.conf file for the AuthTrans directive. The entry should read:

AuthTrans fn="SiteMinderAgent"

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 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:

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.