Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for J2EE Agents

Enabling Port Check Functionality in J2EE Agents

In situations when OpenSSO Enterprise and the deployment container are installed on the same system but on different ports, certain browsers may not send the HOST header correctly to the agent in situations where there are redirects involved between OpenSSO Enterprise Authentication Service and the agent. In such situations, the agent, relying on the availability of the port number from the deployment container, might misread the port number that the user is trying to access.

When such a situation occurs, it can have a severe impact on the system since the agent now senses a resource access that in reality did not occur and consequently the subsequent redirects as well as any policy evaluations may fail thereby making the protected application inaccessible to the end user.

This situation can be controlled by enabling port check functionality on the agent. This is controlled by the property labeled Port Check Enable (Tab: Miscellaneous, Name: com.sun.identity.agents.config.port.check.enable).

When this property is enabled, the agent verifies the correctness of the port number read from the request against its configuration. The configuration that provides the reference for this checking is set by the property labeled Port Check Setting (Tab: Miscellaneous, Name: com.sun.identity.agents.config.port.check.setting).

This property allows the agent to store a map of various ports and their corresponding protocols. When the agent is installed, this map is populated by the preferred port and protocol of the agent server as specified during the installation. However, if the same agent is protecting more than one HTTP listeners, you must add that information to the map accordingly.

When the agent discovers an invalid port in the request, it takes corrective action by sending some HTML data to break the redirection chain so that the browser can reset its HOST header on the subsequent request. This content is read from the file that resides in the locale directory of agent installation. The name of the file is controlled by the property labeled Port Check File (Tab: Miscellaneous, Name: com.sun.identity.agents.config.port.check.file).

This property can also be used to specify the complete path to the file that may be used to achieve this functionality. This file contains special HTML that uses a META-EQUIV REFRESH tag in order to allow the browser to continue automatically when the redirect chain is broken. Along with this HTML, this file must contain the string am.filter.request.url, which is dynamically replaced by the actual request URL by the agent.

You can modify the contents of this file or specify a different file to be used, if necessary, so long as it contains the am.filter.request.url string that the agent can substitute in order to construct the true request URL with the correct port. The contents of this file should be such that it should either allow the user to automatically be sent to this corrected location or let the user click a link or a button to achieve the same result.