Use Web Agents with Proxy Servers 129 - CA SiteMinder. Web Agent Guide. r6.x QMR6. Second Edit

Chapter 10: Use Web Agents with Proxy Servers

This section contains the following topics:

Configure Agents that Sit behind Proxy Servers (see page 130) Security Considerations (see page 135)

130 Web Agent Guide

Configure Agents that Sit behind Proxy Servers

If a Web Agent will be installed behind a proxy server, you can configure the Web Agent to work with proxy servers using the following parameters:

ProxyTrust

Instructs the Web Agent operating on a destination server to trust the authorizations received by another SiteMinder Agent operating on a proxy server. This setting increases efficiency because the Web Agent operating on the destination server does not need to reauthorize users.

Default: No ExpireForProxy

Prevents a client from caching content (pages and potentially headers or cookies). When the value of this parameter is set to yes , the Web Agent inserts one of the following HTTP headers into the HTTP response:

■ Expires

■ Cache-control

If content is not cached, subsequent requests continue to be forwarded.

When the ExpireForProxy parameter is set to yes, the Web Agent inserts the strings specified in the appropriate ProxyHeaderssuffix_name parameter into the HTTP response based upon what type of request the Agent performed.

For HTTP/1.1 requests, the Agent inserts the values of the following parameters as headers in the response:

■ ProxyHeadersAutoAuth

■ ProxyHeadersProtected

■ ProxyHeadersUnprotected

For HTTP/1.0 requests, the Agent inserts the values of the following parameters as headers in the response:

– ProxyHeadersAutoAuth10 – ProxyHeadersProtected10

■ ProxyHeadersUnprotected10 Default: No

Note: Although this parameter name contains the word 'proxy,' the settings of this parameter also affect the behavior of web browsers, or any other client that connects to a web server on which any SiteMinder Agents using this parameter setting operate.

Control How HTTP Header Resources are Cached

Chapter 10: Use Web Agents with Proxy Servers 131 To tell the proxy not to cache the pages, the Web Agent adds an Expires header for the page. This header is set to a date in the past, which prevents the page from being cached by a proxy, as dictated by the HTTP 1.0 specification. On 302 redirects, a cache-control: no-cache header is set instead. Although this prevents caching of content, this has the negative consequence of affecting the browsing experience for an Internet Explorer (IE) browser, as described by Microsoft Support.

With the use of cache-control: no-cache for 302 redirects, the ActiveX component that manages in-place document viewing in IE relies on the browser’s cache to locate the file.

Because this header instructs the browser not to cache the file, the ActiveX component cannot locate the file and fails to display the request properly. Further, when you set the Web Agent’s ExpireForProxy setting to yes, the back-end server tells the proxy not to cache the resource.

To configure Agents that sit behind proxy servers 1. Set the ProxyTust parameter to yes.

2. Set the ExpireForProxy parameter to yes.

3. (Optional) Customize values the cache-control and ExpireForProxy (HTTP) headers.

The Agents behind the proxy servers are configured.

More information:

Customize the Cache-Control and ExpireForProxy Header Settings (see page 132)

132 Web Agent Guide

Customize the Cache-Control and ExpireForProxy Header Settings

You can customize the cache-control and ExpireForProxy headers to secure Web resources without affecting in-place activation of application files (.doc, .pdf, and so on).

You can set specific HTTP headers for the following types of content independently to control how that content is cached by a web browser or proxy server:

■ Auto-Authorized

■ Unprotected

■ Protected

Important! We recommend using the default settings unless you are familiar with the ramifications of changing these settings in accordance with RFC 2068. If you plan to change the default settings, note that the SiteMinder session cookie is updated on access of an unprotected page once a user has a session in order to track idle timeout.

Therefore, unprotected pages should not be cached on a proxy that caches HTTP headers.

The following characteristics apply to setting headers to prevent caching by proxies:

■ All redirects set a Cache-Control: no-cache header, regardless of agent activity.

■ The web server sends the appropriate headers back to the proxy/client based on the HTTP protocol used (1.0 or 1.1 and higher).

All parameters should be configured using multi-value strings to suit the use of multiple headers, such as cache-control: private and cache-control: max-age=60.

The following is the new configuration:

1. ProxyHeadersDefaultTime - defaults to 60 seconds 2. ProxyHeadersTimeoutPercentage – defaults to 10 percent 3. The following cache-control headers are available:

ProxyHeadersAutoAuth

Specifies the value of an HTTP 1.1 header that the Web Agent inserts into an HTTP response to a client when the ExpireForProxy parameter in the Web Agent Configuration is set to yes. The value of this header determines if or for how long the auto-authorized resource is cached.

Default: Expires: Thu, 01 Dec 1994 16:00:00 GMT

Example (suggested setting): "Cache-control: max-age=60"

Control How HTTP Header Resources are Cached

Chapter 10: Use Web Agents with Proxy Servers 133 ProxyHeadersAutoAuth10

Specifies the value of an HTTP 1.0 header that the Web Agent inserts into an HTTP response to a client when the ExpireForProxy parameter in the Web Agent Configuration is set to yes. The value of this header determines if or for how long the auto-authorized resource is cached.

Default: Expires: Thu, 01 Dec 1994 16:00:00 GMT

Example (suggested setting): "Expires: Thu, 01 Dec 1994 16:00:00 GMT"

ProxyHeadersProtected

Specifies the value of an HTTP 1.1 header that the Web Agent inserts into an HTTP response to a client when the ExpireForProxy parameter in the Web Agent Configuration is set to yes. The value of this header determines if or for how long the protected resource is cached.

Default: Expires: Thu, 01 Dec 1994 16:00:00 GMT Cache-Control: no-cache

Example (suggested settings): "Cache-Control: private"

ProxyHeadersProtected="Cache-Control: max-age=60"

ProxyHeadersProtected10

Default: Expires: Thu, 01 Dec 1994 16:00:00 GMT Cache-Control: no-cache

Example (suggested settings): "Expires: Thu, 01 Dec 1994 16:00:00 GMT"

ProxyHeadersUnprotected

Default: Expires: Thu, 01 Dec 1994 16:00:00 GMT Cache-Control: no-cache

Example (suggested setting): ProxyHeadersUnprotected="Cache-Control:

private"

ProxyHeadersUnprotected="Cache-Control: max-age=60"

134 Web Agent Guide

ProxyHeadersUnprotected10

Default: Expires: Thu, 01 Dec 1994 16:00:00 GMT Cache-Control: no-cache

Example (suggested setting): "Expires: Thu, 01 Dec 1994 16:00:00 GMT"

When configuring multiple headers, (for example, the cache-control headers in the suggested setting for unprotected HTTP/1.1 content), note the following:

■ You must have multiple occurrences of the configuration parameter and you cannot separate these with a comma (,) or the plus-sign (+).

■ As the values for these configuration parameters are HTTP response headers, they must comply with RFC 2616 (for HTTP/1.1), RFC 1945 (for HTTP/1.0) and RFC 822.

Both HTTP/1.1 and HTTP/1.0 specify the format for an HTTP Header as that of an RFC 822 message, namely "Name: Value" (Name, followed by a colon, white space and then a value).

If you do not configure the Web Agent to set the appropriate cache expiration headers when a user accesses unprotected resources, then by default, the Web Agent will not set these headers, thereby allowing a web browser or proxy server to cache an SMSESSION cookie. This cached cookie can be re-used by the web browser or proxy-server after the user has initiated a different session (and therefore a different user context), causing an unauthorized impersonation.

More information:

Configure Agents that Sit behind Proxy Servers (see page 130)

Proxy Header Usage Notes

■ To prevent the Web Agent from sending any proxy headers, blank out the ProxyHeadersUnprotected value. For example:

ProxyHeadersUnprotected=""

Note: To get a double quote character (“) to appear, use a single quote (‘). The Web Agent automatically converts it to a double quote.

■ The value, %% or %d (treated identically) may appear within a ProxyHeaders line.

This value is replaced with either the smaller of the IdleTimeout and

SessionTimeout multiplied by the ProxyHeadersTimeoutPercentage, or, if the timeouts are not set, the ProxyHeadersDefaultTime is used.

Control How HTTP Header Resources are Cached

Chapter 10: Use Web Agents with Proxy Servers 135

■ Ensure that values for the standard (1.1 and higher) and HTTP 1.0 headers are set properly for requests to the back-end server.

■ ExpireForProxy="YES" will expire cookie provider redirects carrying the SMSESSION cookie in the query string.

Security Considerations

Browser sessions can persist after logout, so removing the SMSESSION cookie does not prevent a user from using the same browser session to view previously cached files. This problem occurs because the proxy server is not aware of the logout request and retains any protected/unprotected content in cache for the cache-control: private user until it timed out (cache-control: max-age=60). Thus, such a request would result in a page returned with a valid SMSESSION cookie. The only way to ensure security is to disable keep-alives or close the browser.

Further, the local browser cache is affected by the private/max-age combination since it observes local cache across sessions. For this reason, the max-age time for protected resources should be as short as possible.

Employing the if-modified-since and if-none-match request headers when the

allowcacheheaders="FALSE" configuration setting is used (default) does not prevent the proxy server from observing these headers. Thus, these observed headers take effect on the request according to the proxy server.

You could work around this issue by installing:

■ a Web Agent on the proxy server.

■ another filter that removes these headers from the request.

Since HTTP 1.0, HTTP 1.1, or higher use different headers for specifying instructions to caching proxies, these versions should be configured in a way to ensure the most appropriate handling based on the type of connection.

136 Web Agent Guide

Use Lower Case HTTP in Headers (for Oracle iPlanet, Apache, and Domino web servers)

If you have server applications that are case-sensitive, you can specify the case of the Agent’s HTTP headers. The Web Agent defaults to lower case headers.

For example, Oracle iPlanet web servers, by default, provide the HTTP header variables in lower-case, such as http_sm_user.

Note: IIS Web Agents do not benefit from this feature, because IIS forces all headers to an upper case format.

To use lower case headers, set the LowerCaseHTTP parameter to yes. If you require upper-case header variables, set LowerCaseHTTP to no.

More information:

Record the Transaction ID in Oracle iPlanet Web Server Logs (see page 159)

Set the HTTP Header Encoding Spec

The HTTPHeaderEncodingSpec setting affects the encoding of all HTTP header values and all custom HTTP-COOKIE responses.

Use this parameter to support Web applications expecting localized text in specific encodings. Since cookies pass back and forth between the browser and portal through the HTTP protocol, you should use the RFC-2047 HTTPWrapSpec if your chosen encoding puts characters that HTTP traffic considers illegal into the cookies.

For example, some Shift-JIS characters will cause undesirable results if not further encoded by RFC-2047.

For Kanji characters, you can use SECP932, which is a superset of SHIFT-JIS. Though SHIFT-JIS can be used for most Kanji encoding and decoding, CP932 covers an even larger character set.

When HTTPWrapSpec is used, first the data is encoded according to the

HTTPHeaderEncodingSpec, then the data is further encoded following the RFC-2047 specification.

Disable Conformance to RFC 2047

Chapter 10: Use Web Agents with Proxy Servers 137 The syntax for the parameter is:

encoding_spec, wrapping_spec

The encoding_spec is a text string that represents one of the following encoding types:

UTF-8, Shift-JIS, EUC-J, or ISO-2022 JP. Specify the encoding type you want the Agent to use.

The wrapping_spec is the wrapping specification, which must be RFC-2047. Although this variable is optional, we strongly recommend that you include the wrapping specification because the encoding type you choose may generate byte codes that are not compatible with the HTTP protocol.

This is especially true if you use custom HTTP Cookie responses that contain double-byte encoded data. For example, some Shift-JIS characters cause undesirable results if they are not further encoded by RFC-2047. The wrapping also tells the receiving application the type and nature of the encoding so the application can better interpret the encoded text. For example, you may set the parameter to Shift-JIS,RFC-2047.

When RFC-2047 is used, the Agent first encodes the data based on the chosen encoding specification and then further encodes the data following the RFC-2047 specification.

Note: If you leave the HTTPHeaderEncodingSpec setting blank, the default is UTF-8 with no wrapping.

Disable Conformance to RFC 2047

By default, the Web Agent conforms to RFC 2047. However, you can disable this conformance by setting the ConformToRFC2047 parameter to no.

If this parameter does not exist or is set to yes, the Web Agent conforms to RFC 2047.

Use SM_AGENT_ATTR_USRMSG Response for a Forms Challenge

The SM_AGENTAPI_ATTR_USERMSG response enables developers of custom SiteMinder authentication schemes to return custom text to their client applications, as part of a user challenge or for some other purpose.

Beginning with v5 QMR3, the Web Agent has the ability to convert the text from an SM_AGENTAPI_ATTR_USERMSG response to an SMUSRMSG cookie when performing a forms challenge.

138 Web Agent Guide

To ensure the SMUSRMSG cookie is removed after the challenge is complete, the FCC consumes the cookie (deletes it from the browser) after a successful POST request, as follows:

■ In native SiteMinder mode, the Agent deletes the cookie after a successful login, while redirecting back to the target URL.

■ In SiteMinder 4.x compatibility mode, the Agent deletes the cookie after generating the FORMCRED cookie, while redirecting back to the target URL.

Note: The SMUSRMSG cookie will be stored for a period of time in the user's browser, and could possibly be transmitted over non-secure HTTP connections. As a result, sensitive data should be avoided.

Web Agents will URL-encode text that is placed in the SMUSRMSG cookie during a forms challenge, to make it safe for HTTP transmission, eliminating spaces and other harmful characters. The FCC decodes this text before making it available to the environment for use in custom FCC functionality.

Note: URL encoding is not implemented unless the text is placed in the SMUSRMSG cookie.

To implement the new functionality, custom authentication scheme developers must generate custom forms-based authentication schemes. When an Sm_AgentApi_Login() call returns SM_AGENTAPI_CHALLENGE, the Agent challenges the requesting user by redirecting to the authentication scheme URL provided by the response to

Sm_AgentApi_IsProtected().

When the Web Agent handles an authentication scheme that uses the HTML Forms authentication scheme template, the Agent looks for a

SM_AGENTAPI_ATTR_STATUS_MESSAGE response attribute. If the attribute is found, the Agent generates the appropriate SMUSRMSG cookie, while redirecting to the authentication scheme URL. The FCC may then use this cookie during form generation, if appropriate directives are placed in the desired .FCC source file.

Note: For more information, see the Policy Server documentation.

Enable Legacy Variables for HTTP Headers

Chapter 10: Use Web Agents with Proxy Servers 139

Enable Legacy Variables for HTTP Headers

You can specify which naming convention the Web Agent uses for HTTP headers with the following parameter:

LegacyVariables

Specifies if the Web Agent uses underscores in HTTP header names. With some web servers (such as the Sun Java System), using the underscore character in the HTTP headers causes problems with some applications.

When this parameter is set to no, the HTTP headers will not have underscores, as shown in the following example:

SMHeaderName

When this parameter is set to yes, the HTTP headers will use underscores, as shown in the following example:

SM_HeaderName

Default: (traditional agents) Yes Default: (framework agents) No

To enable legacy variables and have the Web Agent use underscores in the HTTP header names, set value of the LegacyVariables parameter to yes.

Define HTTPS Ports

If you are using an SSL connection to the web server (HTTPS) to keep your requests more secure, you must specify the HTTPS ports 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: 80

Example: (multiple ports) 80,8080,8083

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.

140 Web Agent Guide

Use the HttpsPorts Parameter on Apache 2.x Servers

To use the HttpsPorts parameter with an Apache 2.x Web server (if you plan to use an SSL accelerator with the Apache Web server, for example) make additional

configuration changes to your Web server. These changes are required if you use an SSL accelerator or any intermediate device that changes the value of the HTTP_HOST header.

To use the HttpsPorts Parameter with Apache 2.x servers

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

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

In document CA SiteMinder. Web Agent Guide. r6.x QMR6. Second Edition (Page 129-145)