Administration Guide › Configuring Proxy Rules

Configuring Proxy Rules

This section contains the following topics:

Proxy Rules Overview

Establish a Proxy Rules Configuration File

Proxy Rules DTD

How nete:xprcond Elements Works

Regular Expression Syntax

Header Values in Forwards, Redirects, and Results Filters

Response Handling

Modify Proxy Rules

Sample Proxy Rules Configuration Files

Proxy Rules Overview

The primary purpose of the CA SiteMinder® SPS is to route requests to the appropriate destination servers in the enterprise. The CA SiteMinder® SPS routes requests using the proxy engine, which is built into the server. The proxy engine interprets proxy rules and provides both a forward and a redirect service to handle the disposition of all user requests for back end resources.

Proxy rules define the details of how the CA SiteMinder® SPS forwards or redirects requests to resources located on destination servers within the enterprise. A set of proxy rules is defined in an XML configuration file according to the proxy rules DTD, which is installed with the SPS.

Note: The proxyrules.xml file contains a default rule that forwards requests to http://www.ca.com$0, where $0 appends the entire URI from the original request to the destination, which is www.ca.com in this case. You must modify this rule to suit your environment.

More information:

Proxy Rules DTD

Planning Routes for Incoming Requests

Before you set up the proxyrules.xml file, you should map out the routing for incoming requests. Depending on the virtual host that contains the requested resource, the proxy rules can use a default destination; forward a request based on the user agent type, or uses a HTTP header value to determine the destination server that will fulfill the request. The CA SiteMinder® SPS can provide access to a number of virtual hosts.

The following illustration shows how proxy rules can be used to route requests to appropriate destination servers.

Note: A proxy rules configuration file is processed from top to bottom by the SPS. The first condition that is met by an incoming request determines the behavior of the proxy engine. For example, if a set of proxy rules has two conditions based on a string contained in the URI of a request, and part of the URI of an incoming request matches both of the strings, the first condition listed in the proxy rules file will be used to route the request.

Proxy rules can also be used to control more complex conditions for directing requests to destination servers.

The following illustration shows how proxy rules can be used with a second level of conditions nested within parent conditions.

Proxy Rules Terminology

The proxy rules configuration file is a description of the XML elements that the CA SiteMinder® SPS uses when routing user requests. The following terms are used to describe the proxy rules:

Destinations

A destination is a URL that fulfills a request. The CA SiteMinder® SPS forwards a request to a destination, or sends a redirect response to a user that specifies a destination. A set of proxy rules must contain destinations that can be reached according to the conditions and cases defined in the proxy rules.

Conditions

A condition is an attribute of a request that allows the CA SiteMinder® SPS to determine the destination of a request. Each condition may have many cases that the CA SiteMinder® SPS evaluates to direct a request to the appropriate destination. Each condition must contain a default element that defines the behavior if a request does not match any of the cases defined in the condition.

The conditions may include any one or more of the following:

URI

The CA SiteMinder® SPS uses the portion of the requested URL after the hostname to determine how to route a request. Using criteria described in the DTD, a portion of a URI, such as the file extension of the requested resource, can be used to route requests.

Query String

The CA SiteMinder® SPS uses the query string portion of a URI to determine how to route a request. The query string includes all the characters following a '?' in the request.

Host

The CA SiteMinder® SPS uses the requested server hostname to determine how to route a request. The port number of the hostname can also be used as criteria for routing requests. This condition is used when the proxy has more than one virtual server.

Header

The CA SiteMinder® SPS uses the value of any HTTP header to determine how to route a request. To route requests based on the type of device being used to access resources, requests may be routed according to the USER_AGENT HTTP header.

Note: HTTP headers derived from SiteMinder responses may be used to determine how to route a request.

Cookie

The CA SiteMinder® SPS uses the existence or value of a cookie to determine how to route a request. If a cookie value is encoded, specify the encoding scheme in encoding parameter. The CA SiteMinder® SPS supports only the base64 encoding scheme.

Cases

A case is a set of specific values for conditions that provide the information the CA SiteMinder® SPS needs to determine the ultimate destination for a request. For example, if a set of proxy rules uses the host condition, cases include the virtual hosts configured for the system, such as home.company.com and banking.company.com.

Establish a Proxy Rules Configuration File

The proxy rules configuration file is an XML configuration that is identified by the rules_file directive of the <ServiceDispatcher> element in the server.conf file. The rules_file directive indicates the relative path from the installation directory to the proxy rules configuration file. At installation, the relative path to the default proxy rules configuration file is generated automatically and inserted into the rules_file directive for the default virtual host.

The generated path and proxy rules file name is the following:

sps_home/secure-proxy/proxy-engine/conf/proxyrules.xml

All the entries in the proxyrules.xml file must be well-formed and satisfy the syntax rules as per the XML specifications. Changes to the proxy rules configuration file do not require a server restart to take affect; the CA SiteMinder® SPS detects when changes are made to the file and loads the new proxy rules file.

If the CA SiteMinder® SPS detects an error in the proxy rules when parsing the rules, the CA SiteMinder® SPS records an error in the server log, ignores the changes, and uses the existing proxy rules. The server log file location is specified in the logger.properties file.

Proxy Rules DTD

You must create the proxyrules.xml file using the proxy rules DTD. To view the proxy rules DTD, go to the following directory:

sps_home\secure-proxy\proxy-engine\conf\dtd

The following elements are configurable in the DTD:

• nete:proxyrules
• nete:description
• nete:case
• nete:cond
• nete:default
• nete:forward
• nete:redirect
• nete:local
• nete:xprcond

nete:proxyrules

The full definition for the nete:proxyrules element is:

<!ELEMENT nete:proxyrules (nete:description?,(nete:cond | nete:forward | nete:redirect | nete:local)) >

This element is the root element for a proxy rules XML configuration file. It contains an optional nete:description element and one of the following elements:

• nete:cond
• nete:xprcond
• nete:forward
• nete:redirect
• nete:local

The nete:proxyrules element must be present in a proxy rule configuration file.

Debug Attribute

The nete:proxyrules element has the following attribute:

<ATTLIST nete:proxyrules
debug (yes|no) "no"

This attribute enables or disables logging that aids in debugging proxy rules. The default for this attribute is no. To enable logging, set this attribute to yes.

For example:

<nete:proxyrules xmlns:nete="http://www.company.com/" debug="yes">

When enabled, trace logging information for the CA SiteMinder® SPS is included in trace logs. The location of the log file is determined by the TraceFileName parameter in the agent configuration object that you specified during the CA SiteMinder® SPS installation process. The TraceConfigFile parameter in the same agent configuration object must point to the Secure Proxy-specific trace logging configuration file.

By default this file is located in:

<install-dir>\proxy-engine\conf\defaultagent\SecureProxyTrace.conf

Note: This change does not require a CA SiteMinder® SPS restart for the changes to take effect.

nete:description

The full definition for the nete:description element is:

<!ELEMENT nete:description (#PCDATA)>

This is an optional element that contains a parsed character data (PCDATA) description of another element.

Note: PCDATA is any text that is not markup text.

A nete:description element can be a child of the nete:proxyrules element and may contain a description of your choosing.

nete:case

The nete:case element provides the destination associated with a specific value for a condition defined in the nete:cond parent element. The SPS uses the value of the nete:case element to evaluate a case.

The definition for the nete:case element is:

<!ELEMENT nete:case (nete:cond | nete:xprcond | nete:forward | nete:redirect | nete:local)>

All nete:case elements must contain one of the following child elements:

nete:cond

nete:case elements can contain additional nete:cond elements. This allows you to nest multiple conditions in a set of proxy rules.

nete:xprcond

nete:case elements can contain additional nete:xprcond elements for regular expression matching of URIs. This allows you to nest a regular expression condition in a set of other conditions.

nete:forward

Provides a destination to which requests that fulfill the nete:case comparison will be forwarded.

nete:redirect

Provides a destination to which requests that fulfill the nete:case comparison will be redirected. Once redirected, requests are fulfilled directly by the destination server, rather than through the SPS.

In the following example, a nete:cond element specifies URI matching, and the nete:case elements demonstrate possible uses of the comparison type attribute.

<nete:cond type="uri" criteria="beginswith">

<nete:case value="/hr">
  <nete:forward>http://hr.company.com$0</nete:forward>
	</nete:case>
	<nete:case value="/employee">
	   <nete:forward>http://employees.company.com$1
			</nete:forward>
	</nete:case>
</nete:cond>

Note: The <nete:forward>URL</nete:forward> elements must be located on the same line. In the example, the </nete:forward> closing tags sometimes appear on a separate line due to space constraints, however, a line break in an actual proxy rules file causes an error. The SPS interprets line breaks before the </nete:forward> closing tag as characters that are part of the URL contained in the nete:forward element.

Forward and Redirect Syntax

When forwarding or redirecting a request, the SPS uses a system for maintaining some part or all of the Universal Resource Indicator (URI) specified by a user. This URI points to a resource that lies on a destination server and must be interpreted by the SPS to fulfill a request.

Either of the following may be appended to a URL specified in a forward or redirect destination:

$0

Appends the entire URI string from a user’s request to the destination specified in the proxy rule.

For example, if a proxy rule forwards all user requests for www.company.com to proxy.company.com$0 and a user request for proxy.company.com/employees/hr/index.html, that request is forwarded to www.company.com/employees/hr/index.html.

$1

May only be used in nete:case elements where the parent nete:cond element specifies a URI substring match using the begins with comparison. $1 indicates that everything to the right of the matching text is appended to the forwarded or redirected request.

For example, consider a proxy rules configuration file that has a nete:cond element of:

<nete:cond type="uri" criteria="beginswith">

Assume this condition is the child of a condition that is evaluating URIs for a hostname of www.company.com and a nete:case element of:

<nete:case value="/hr">

<nete:forward>http://hr.company.com$1</nete:forward>
</nete:case>

If a user requests:

http://www.company.com/hr/employees/index.html

The request is forwarded to:

http://hr.company.com/employees/index.html

Note: Because this example specifies the $1 parameter, the /hr portion of the URI is omitted when the request is forwarded to hr.company.com.

nete:cond

The definition for the nete:cond element is:

<!ELEMENT nete:cond (nete:case+,nete:default)>

In addition, the nete:cond element has the following attributes:

<!ATTLIST nete:cond type (header | host | uri | query | cookie) #REQUIRED
criteria (equals | beginswith | endswith | contains | exists) "equals"
headername CDATA #IMPLIED>

The nete:cond element specifies a condition that will be evaluated to determine how the CA SiteMinder® SPS handles incoming requests. This element must include an attribute to be evaluated by the SPS.

Possible attributes, as defined in the ATTLIST element, include:

header

Specifies an HTTP header. HTTP headers are name-value pairs which can be retrieved from a user directory by SiteMinder. If you select header as the type, you must also specify the name of the header. The following is an example of a nete:cond element using header as the type:

<nete:cond type="header" headername="USER_AGENT">

This element indicates that a header will be used to determine the destination of a request, and that the header to be evaluated by the CA SiteMinder® SPS is USER_AGENT. The actual destinations for requests are determined by nete:case elements which are children of nete:cond elements as described in the next section.

Conditions that use headers as the comparison require an additional argument of headername="value" where value is the name of the HTTP or SiteMinder header.

Note: HTTP headers generated by SiteMinder responses may be specified in nete:cond elements.

host

Specifies a host name in deployments where the CA SiteMinder® SPS proxies for multiple virtual hosts.

Port numbers are considered part of the host, so you can use the endswith criteria, described later, in conjunction with the host condition to route requests by port number.

query

Specifies the query string portion of the URI that follows the '?' character. This is similar to a nete:cond that makes use of the URI as follows:

URI

Specifies universal resource indicator, which is the portion of a requested URL that follows the server name.

You can use the endswith criteria in conjunction with the URI condition to route requests by file extension.

cookie

Specifies a cookie attribute to determine how to route a request. If a cookie value is encoded, specify the encoding scheme in encoding parameter. The CA SiteMinder® SPS supports only the base64 encoding scheme and does not support cookie creation. The following are the possible cases of an encoded cookie:

• If a cookie is encoded using base64, specify the cookie value in the value attribute and base64 as the encoding parameter in the nete:case element. The CA SiteMinder® SPS uses the base64 encoding algorithm to decode the cookie value received from a httprequest and compares the result the decoded value with the value specified in the value attribute.
• If a cookie is not encoded, enter the cookie value in plain text in the value attribute and you can specify the encoding parameter as blank in the nete:case element. The CA SiteMinder® SPS accepts the specified plain text as the cookie value and verifies the nete:cond.

If a cookie is encoded using a different encoding scheme, enter the encoded cookie value in the value attribute and specify the encoding parameter as blank in the nete:case element. The CA SiteMinder® SPS accepts the specified encoded cookie value as plain text, and uses the plain text cookie value to verify the nete:cond

One of the type attributes described above must be included in the nete:cond element. In addition, the nete:cond element must specify a criteria that defines the comparison that the proxy engine executes on the value of the condition for an incoming request. Possible criteria are:

equals

Indicates that the value of the type attribute of the nete:cond parent element must equal the contents of the value attribute of the nete:case element to act on a request.

beginswith

Indicates that the value of the type attribute of the nete:cond parent element must begin with the contents of the value attribute of the nete:case element to act on a request.

endswith

Indicates that the value of the type attribute of the nete:cond parent element must end with the contents of the value attribute of the nete:case element to act on a request.

contains

Indicates that the value of the type attribute of the nete:cond parent element must contain the contents of the value attribute of the nete:case element to act on a request.

exists

Indicates that the nete:cond parent element must exist and the value attribute of the nete:case element must be true to act on a request. You can use the exists criteria with only header and cookie attributes.

Note: If no criteria are specified, the CA SiteMinder® SPS assumes the default criteria of equals.

Each nete:cond element must have one or more nete:case child elements. The nete:case children provide the unique values that the CA SiteMinder® SPS uses to route requests to appropriate destinations.

nete:default

The definition of the nete:default element is:

<!ELEMENT nete:default (nete:cond | nete:xprcond | nete:forward | nete:redirect | nete:local)>

This element is required and must be a child element of each nete:cond element. If a request does not meet the requirements of any nete:case elements contained in nete:cond elements, the nete:default element determines how to handle the request.

The possible child elements associated with the nete:default element are identical to the elements available for a nete:case element. If you create nete:cond elements as children to a nete:default, be careful to take into account a default case so that all possible client requests may be handled by the SPS.

In the following example, the nete:default element forwards all requests that do not meet the criteria of any other proxy rules to a home page of general information.

<nete:default>

<nete:forward>http://home.company.com/index.html 
</nete:forward>

</nete:default>

The opening and closing tags, <nete:forward>URL</nete:forward>, elements must be located on the same line. In the example, the </nete:forward> closing tags sometimes appear on a separate line due to space constraints, however, a line break in an actual proxy rules file causes an error. The CA SiteMinder® SPS interprets line breaks before the </nete:forward> closing tag as characters that are part of the URL contained in the nete:forward element.

nete:forward

The definition of the nete:forward element is:

<!ELEMENT nete:forward (#PCDATA)>

The nete:forward element forwards a request to a specified URL.

Note: The <nete:forward> and </nete:forward> tags must be located on a single line in the proxy rules file. If they are not located on the same line, the CA SiteMinder® SPS interprets line breaks as part of the URL contained in the element. This causes the forward service to fail.

In the following example, the nete:forward element forwards requests while maintaining the URI requested by the user.

<nete:forward>http://home.company.com$0</nete:forward>

If the user’s request satisfies the nete:case parent element’s criteria, that request is forwarded to home.company.com. Therefore, a request for http://server.company.com/hr/benefits/index.html that is forwarded by the previous nete:forward element is fulfilled by forwarding the request to http://home.company.com/hr/benefits/index.html.

If you want to forward a request over SSL, be sure to use https instead of http when defining the destination contained in the <nete:forward> element.

The nete:forward element contains the following attribute:

<!ATTLIST nete:forward filter CDATA #IMPLIED>

This attribute allows you to specify the name of a Java filter class that can be invoked during a forward from the CA SiteMinder® SPS to a destination server. Filters can be written using the Filter API.

More information:

Forward and Redirect Syntax

Filter API Overview

The nete:forward element contains the following attribute:

<!ATTLIST nete:forward filter CDATA #IMPLIED>

This attribute allows you to specify the name of a java filter class that can be invoked during a forward from the CA SiteMinder® SPS to a destination server. Filters can be written according to the Filter API.

nete:redirect

The definition of the nete:redirect element is:

<!ELEMENT nete:redirect (#PCDATA)>

The nete:redirect element specifies a response that is returned to a user which redirects the user request to an appropriate destination server. The PCDATA follows the standard forward and redirect syntax. Once redirected, the CA SiteMinder® SPS does not handle the completion of the request. Instead, the request is handled by the server that is the target of the redirection.

The <nete:redirect> and </nete:redirect> tags must be located on a single line in the proxy rules file. If they are not located on the same line, the CA SiteMinder® SPS interprets line breaks as part of the URL contained in the element. This causes the redirect service to fail.

In the following example, the nete:redirect element redirects requests while maintaining the URI requested by the user. Unlike a nete:forward element, once the request has been redirected, the CA SiteMinder® SPS is removed from the transaction, and the destination server provides resources directly to the user.

<nete:redirect>http://home.company.com$0</nete:redirect>

If a user’s request for http://www.company.com/hr/index.html meets a parent nete:case element’s criteria and is redirected by the above example, the user is redirected and the user’s browser displays the URL of the destination server fulfilling the request:

http://home.company.com/hr/index.html

Note: If you want to redirect a request over SSL, be sure to use https instead of http when defining the destination contained in the <nete:redirect> element.

More information:

Forward and Redirect Syntax

nete:local

The nete:local element is included to support future functionality, and should not be included in proxy rules configuration files.

nete:xprcond

The nete:xprcond element may be used like a nete:cond element in situations where you want to apply regular expressions as conditions in your proxy rules. Regular expressions can be used to evaluate the URI string and any attached query string in your proxy rules.

The definition of the nete:xprcond element is:

<!ELEMENT nete:xprcond (nete:xpr+, nete:xpr-default)>

This element must contain one or more nete:xpr elements and a single nete:xpr-default element.

nete:xpr and nete:xpr-default

A nete:xpr element is similar to a nete:cond element, and contains other elements for a rule based on a regular expression as well as a resulting behavior when the CA SiteMinder® SPS finds a match for the expression. A nete:xpr-default element contains the default behavior for URI or query string combinations that do not match any of the regular expressions contained in the nete:xpr elements within a nete:xprcond element.

The definition of a nete:xpr element is:

<!ELEMENT nete:xpr (nete:rule, nete:result)>

A nete:xpr element contains a nete:rule element that defines a regular expression, and a nete:result element that specifies the behavior for strings that match the regular expression.

The definition of a nete:xpr-default element is:

<!ELEMENT nete:xpr-default (nete:forward|nete:redirect|nete:local)>

The nete:xpr-default element specifies a forward or redirect that should be completed if the URI or query string being evaluated by the CA SiteMinder® SPS does not match the conditions stated in any of the nete:xpr elements contained in the parent nete:xprcond element.

nete:rule and nete:result

The nete:rule and nete:result elements must be contained in a nete:xpr element. The nete:rule element specifies the regular expression that the SPS evaluates against incoming requests. The nete:result element determines the behavior for matching requests.

The definition of the nete:rule element is:

<!ELEMENT nete:rule (#PCDATA)>

This element contains a string that is a regular expression. The URI and query string of a request is matched against this regular expression to determine if a request satisfies the nete:xpr condition.

The definition of the nete:result element is:

<!ELEMENT nete:result (#PCDATA)>

nete:result elements may have the following attributes:

<!ATTLIST nete:result service (forward|redirect) "forward">

This element contains a string consisting of the substitution string (URL) by which the SPS creates a URL to pass to a service (forward or redirect). The service attribute is used to specify the appropriate service that will receive the URL. The default service is the forward service defined in the server.conf configuration file.

The substitution URL in the nete:result element should be a URL that optionally contains $#, where # is 0, 1, 2, etc.

• $0 is the entire URI and query string being evaluated.
• $n is the part of the requested URI that matched the nth set of parentheses in the regular expression described in the associated nete:rule element.

For example, a set of proxy rules can contain the following:

<nete:xprcond>

<nete:xpr>

<nete:rule>^/realma(.*)</nete:rule>
<nete:result>http://server1.company.com$1</nete:result>

</nete:xpr>

<nete:xpr-default>

<nete:forward>http://www.company.com$0</nete:forward>

</nete:xpr-default>

</nete:xprcond>

The <nete:result>URL</nete:result> tags must be located on a single line in the proxy rules file. If they are not located on the same line, CA SiteMinder® SPS interprets line breaks as part of the URL contained in the element. This causes the result service to fail.

In the previous nete:xprcond proxy rule example, a request for:

http://www.company.com/realma/index.html

will be forwarded to:

http://server1.company.com/index.html

How nete:xprcond Elements Works

The processing of a nete:xprcond element is similar to the processing of all other nete:cond elements. As the CA SiteMinder® SPS processes requests, and it encounters a nete:xprcond element in the proxy rules configuration file, the following occurs:

1. The CA SiteMinder® SPS examines the first nete:xpr element in the nete:xprcond element.
2. The proxy engine evaluates the regular expression described in the nete:rule element against the URI and query string of the request.
3. If the requested URI and query string matches the regular expression specified in the nete:rule element, then the CA SiteMinder® SPS resolves the result string using the results of the match, and the request is forwarded to the specified service with the URL derived from the nete:result element.
4. If the requested URI and query string do not match the regular expression in the first nete:xpr element, the proxy rules engine evaluates the next nete:xpr element (repeat steps 2 and 3). This process continues until the rules engine finds a match or reaches the nete:xpr-default element.
5. If no match is found before reaching the nete:xpr-default element, then the contents of the nete:xpr-default element determine how to route the request.

Regular Expression Syntax

This section describes the syntax that should be used to construct regular expressions for nete:rule elements. A nete:xprcond element takes the following form:

<nete:xprcond>

<nete:xpr>

<nete:rule>regular_expression</nete:rule>
<nete:result>result</nete:result>

</nete:xpr>
<nete:xpr-default>forward_destination</nete:xpr-default>

</nete:xprcond>

In the nete:xpr element, the nete:rule element must consist of a regular expression that uses the syntax described in the following table. This syntax is consistent with the regular expression syntax supported by Apache and described at http://www.apache.org.

All closure operators (+, *, ?, {m,n}) are greedy by default, meaning that they match as many elements of the string as possible without causing the overall match to fail. If you want a closure to be reluctant (non-greedy), you can simply follow it with a ’?’. A reluctant closure will match as few elements of the string as possible when finding matches. {m,n} closures don’t currently support reluctancy.

Regular Expression Examples in nete:rule and nete:result

Regular expressions offer a very flexible and powerful tool that can be employed in CA SiteMinder® SPS proxy rules. This section provides a few examples nete:rule elements in proxy rules. In addition, the examples also contain various uses of the nete:result element to show how groupings in a nete:rule can be used to affect the destination generated by the children of a nete:xprcond element.

Map Single Rule to Many Destination Servers

In the following example, a nete:rule element contains a regular expression that can be used to forward requests to many different destinations. This example assumes that the CA SiteMinder® SPS will receive URIs that take the following form:

/GOTO=some path and or filename

Consider a nete:xprcond element contains the following child elements:

<nete:xpr>

<nete:rule>/GOTO=(.*)/(.*)</nete:rule>
<nete:result>http://$1/$2</nete:result>

</nete:xpr>

The regular expression in the nete:rule element and the associated nete:result element match URIs that produce a /GOTO=string. Upon finding a match, the CA SiteMinder® SPS uses the first string after the = symbol in the URI as the $1 value of the result, and the value following the first / symbol that appears after the = symbol as the $2 result. The nete:result element combines these elements to create a URL. By default, nete:result elements use the CA SiteMinder® SPS forward service.

For example, if the URI of a request evaluated by the nete:xpr element described above were as follows:

/GOTO=server1.company.com/index.html

Then the regular expression in the nete:rule element would find a match and assign the value of $1 as server1.company.com and the value of $2 as index.html. The nete:result element assembles these values into the following URL:

http://server1.company.com/index.html

This URL is the target which the CA SiteMinder® SPS uses to resolve the request.

Regular Expressions to Redirect Users

The nete:result element can also be used to create a redirect response that is returned to the user requesting the resource. This forces the fulfillment of a request to be handled by a server other the CA SiteMinder® SPS after authentication and authorization. The following is an example of a nete:xpr element that specifies a redirect in the nete:result child element.

<nete:xpr>

<nete:rule>/REDIR=(.*)/(.*)</nete:rule>
<nete:result service="redirect">http://$1/$2</nete:result>

</nete:xpr>

Note: The service attribute instructs the CA SiteMinder® SPS to use the redirect service in place of the default forward service.

Header Values in Forwards, Redirects, and Results Filters

The value of an HTTP header or a SiteMinder response header can be substituted directly into a nete:forward, nete:redirect, or nete:result element. When a URl in a forward or redirect element, or a rule in a result filter element contains {{HEADER_NAME}}, the proxy engine searches for a header in a request that matches the specified header and substitute’s the header value before resolving the forward, redirect, or result. If no matching header is found in a request, the proxy engine substitutes an empty string in place of the header value.

Note: Header names are case sensitive.

Dynamic Header Value in a nete:forward

To use a dynamic header value as part of a nete:forward element, simply insert {{HEADER_NAME}} into the URL portion of the forward. For example:

<nete:forward>http://www.company.com/{{RESPONSE1}}$1</nete:forward>

You can use multiple headers in a single nete:forward element. For example:

<nete:forward>http://www.company.com/{{RESPONSE1}}/{{RESPONSE2}}$1
</nete:forward>

Dynamic Header Value in a nete:redirect

To use a dynamic header value as part of a nete:redirect element, simply insert {{HEADER_NAME}} into the URL portion of the redirect. For example:

<nete:redirect>http://www.company.com/{{RESPONSE1}}$1</nete:redirect>

You can use multiple headers in a single nete:redirect element. For example:

<nete:redirect>http://www.company.com/{{RESPONSE1}}/{{RESPONSE2}}$1
</nete:redirect>

Dynamic Header Value in a nete:result

To use a dynamic header value as part of a nete:result element, simply insert {{HEADER_NAME}} into the URL portion of the result. For example:

<nete:result>http://www.company.com/{{HEADER_NAME}}$1</nete:result>

You can use other features of proxy rules, such as filters, in conjunction with a dynamic header value. For example:

<nete:result filter="filter1">http://$1/$2?{{HEADER_NAME}}</nete:result>

Response Handling

The CA SiteMinder® SPS uses SiteMinder responses to determine a destination for a request. Since transactions that are routed through the CA SiteMinder® SPS include an interaction between the CA SiteMinder® SPS web agent and SiteMinder, any SiteMinder responses gathered during the authentication and authorization process may be used by the CA SiteMinder® SPS to determine the destination of a request.

For example, if a user directory contains information about the account type for a banking web site, the CA SiteMinder® SPS can proxy users with different types of accounts to different destinations. This enables an enterprise to provide a higher quality of service to its best customers. Customers with standard accounts can be handled by one set of destination servers, while customers with premium accounts can be handled by a separate set of high performance destination servers.

Modify Proxy Rules

To modify proxy rules you must edit the proxy rules XML configuration file using a text editor. Since proxy rules are XML files, your proxy rules configuration file must be well-formed and valid. Remember that the tags in a well-formed XML file must all consist of opening and closing tags. To be valid, the file must adhere to the guidelines laid out in the proxyrules.dtd.

Changes to the proxy rules XML configuration file are picked up automatically by the SPS. When the CA SiteMinder® SPS receives a request, it checks whether or not the proxy rules have changed. If the file has changed, the rules are reloaded before fulfilling the request.

Note: If you change the name of the proxy rules XML configuration file in the rules_file directive in the <ServiceDispatcher> element of the server.conf file, you must restart the CA SiteMinder® SPS.

Sample Proxy Rules Configuration Files

The CA SiteMinder® SPS installs several examples of proxy rules configuration files. You can use these example XML files as the basis for your own proxy rules files.

You can find these example files in the directory sps_home\secure-proxy\proxy-engine\examples\proxyrules. We recommend you look at the example file as you are reading the descriptions in this guide.

You may copy and customize a file to suit your needs.

To customize and deploy a proxy rules file

1. Navigate to the directory sps_home\secure-proxy\proxy-engine\examples\proxyrules.
2. Make a copy of the example file you want to use.
3. Customize the content and save the new file under a unique name.
4. Copy the modified file to the directory sps_home/secure-proxy/proxy-engine/conf.
5. Open up the server.conf file to modify the proxy rules section of the file to point to the customized file.

Proxy Rules Example—Routing Requests by Virtual Host

The example file proxyrules_example1.xml file routes requests based on the hostname specified in the request. The example file proxyrules_example10.xml file also routes CA SiteMinder® SPS requests based on the hostname specified in the request, CA SiteMinder® SPS uses the PID in the proxy rule to count of the number of times the proxy rule has been triggered. If you configured CA Wily Introscope to monitor CA SiteMinder® SPS, the count is displayed in CA Wily Introscope data metrics.

In this file, a simple set of proxy rules routes user requests based on the virtual host specified in the requested resource. All requests to the bondtrading.company.com server are forwarded to server2, all requests to banking.company.com are forwarded to server1, and all other requests are forwarded to the companies home server, which is the default for requests that do not match the criteria in any other nete:cond element.

Note: The nete:case elements must specify a port, since the port number is considered as part of the virtual host requested by the user. Use the beginswith criteria to avoid needing port numbers.

The following table illustrates the results of requests using the proxy rules based on virtual hosts.

Proxy Rules Example—Routing Requests by Header Value

The example file proxyrules_example2.xml file routes CA SiteMinder® SPS requests based on the value of an HTTP header. The HTTP header can be a standard header or one created using a SiteMinder response.

Note: For information about SiteMinder responses, see the CA SiteMinder Policy Design.

In this example, assume that the CA SiteMinder® SPS routes requests made to a default virtual host of www.company.com.

In this file, the value of the HTTP header variable "HEADER" determines the destination for the request.

The following table illustrates the results of requests using the proxy rules based on an HTTP header.

Note: You do not need to include the HTTP_ of the header variable name in the nete:cond element. CA SiteMinder® SPS assumes HTTP_ for header variable names.

Proxy rules that use header values are an excellent way to forward requests based on a desired level of service. For example, you can use the value of an HTTP header variable that contains a user account types to distribute requests to high performance servers for customers with premium accounts.

Proxy Rules Example—Routing Requests by Device Type

The example file proxyrules_example3.xml file routes CA SiteMinder® SPS requests based on the type of device used to access the resource.

Note: The user-agent HTTP header value is used to determine how to route requests.

In the file, users who access resources using a browser (user agent contains Mozilla for Web browsers) are forwarded to a Web server, while all other users are forwarded to a wireless server.

The following table illustrates the results of requests using the proxy rules based on a device type.

Proxy Rules Example—Routing Requests with URIs

The example file proxyrules_example4.xml file routes CA SiteMinder® SPS requests based on the URI specified in the user request.

The following table illustrates the results of requests using the proxy rules based on URIs.

Proxy Rules Example—Routing Requests by File Extension

The example file proxyrules_example5.xml file routes CA SiteMinder® SPS requests based on the file extension requested by the user. This is achieved by using the URI condition in combination with the endswith criteria.

In the file, the <nete:forward> and </nete:forward> tags appear on separate lines due to space constraints. However, in your proxy rules configuration files, the opening and closing tags for a <nete:forward> element must appear on the same line. If they do not, the CA SiteMinder® SPS interprets the line break as part of the forward URL, which causes requests to be forwarded incorrectly.

In the previous example, users who access .jsp resources are forwarded to an application server, while wireless users are forwarded to the wireless server. All other users are forwarded to the home server.

The following table illustrates the results of requests using the proxy rules based on file extensions.

Proxy Rules Example—Routing Requests with Nested Conditions

The example file proxyrules_example6.xml file routes CA SiteMinder® SPS requests based on the hostname, certain headers, and device types. This file demonstrates how the CA SiteMinder® SPS can handle complex relationships in a single configuration file.

In the file, the <nete:forward>URL</nete:forward> elements must be located on the same line. In the example, the </nete:forward> closing tags sometimes appear on a separate line due to space constraints, however, a line break in an actual proxy rules file causes an error. The CA SiteMinder® SPS interprets line breaks before the </nete:forward> closing tag as characters that are part of the URL contained in the nete:forward element.

The following table illustrates the results of requests using proxy rules with nested conditions.

Proxy Rules Example—Using Regular Expression in Proxy Rules

The example file proxyrules_example7.xml file routes CA SiteMinder® SPS requests based on nete:xprcond elements that contain regular expressions. Regular expressions are evaluated based on the URI and query string of a request.

In the file, the URI and query string of the request are evaluated against the three regular expressions defined in the nete:xpr elements. If a match is not found against the first nete:xpr element, the CA SiteMinder® SPS tries to match it against the second, and finally the third regular expression. If no matches are found, the nete:xpr-default condition is used to handle the request.

The following table lists the results of requests using the regular expression proxy rules.

Proxy Rules Example—Routing Requests by Cookie Existence

The example file proxyrules_example8.xml file routes CA SiteMinder® SPS requests based on the existence of a cookie.

In this example, if a request contains a cookie header "mycookie", CA SiteMinder® SPS routes the request to www.company.com.

Proxy Rules Example—Routing Requests by Cookie Value

The example file proxyrules_example9.xml file routes CA SiteMinder® SPS requests based on the value of a cookie.

In this example, if a request contains a cookie header "mycookie" and the request does not specify encoding mechanism, CA SiteMinder® SPS routes the request to www.abcd.com. If a request contains a cookie header "mycookie" and the base64 encoding mechanism, CA SiteMinder® SPS routes the request to www.xyz.com.