CA SiteMinder® SPS routes uses the proxy engine that is built into the server to route requests to appropriate servers in the enterprise. 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 how the requests are forwarded or redirected to resources that are located on destination servers. A set of proxy rules is defined according to the proxy rules DTD that is installed by default, and is stored in a proxyrules.xml configuration file. By default during installation, the following relative path to the proxyrules.xml file is generated and used in the rules_file parameter of the <ServiceDispatcher> section of the server.conf file:
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. The changes to the proxyrules.xml file are detected automatically.
Note: CA SiteMinder® SPS supports serving requests sent to the Multi-Byte Character Set (MBCS) URL of the back-end server satisfying the request.
If an error is detected in the proxy rules when parsing the rules, CA SiteMinder® SPS records the error in the server log that is configured in the logger.properties file, ignores the changes, and uses the existing proxy rules.
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.
Before you configure the proxyrules.xml file, map 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 use a HTTP header value to determine the destination server that will fulfill the request. 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.
The proxyrules.xml file is processed from top to bottom. 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 that is 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 proxyrules.xml file is 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 that are nested within parent conditions:
The following terms are used to describe the proxy rules:
Defines a destination URL that fulfills a request. 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.
Defines a condition attributes of a request that determines the destination of the request. Each condition may have many cases that must be evaluated to direct the request to an 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 can include the following options:
Specifies that the portion of the requested URL after the hostname must be used to determine how to route a request. As per the criteria described in the DTD, use a portion of a URI, such as the file extension of the requested resource, to route requests.
Specifies that the query string portion of a URI must be used to determine how to route a request. The query string includes all the characters following a '?' in the request.
Specifies that the requested server hostname must be used 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.
Specifies that the value of any HTTP header must be used 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 CA SiteMinder® responses may be used to determine how to route a request.
Specifies that the existence or value of a cookie must be used to determine how to route a request. If a cookie value is encoded, specify the encoding scheme in encoding parameter. Only the base64 encoding scheme is supported.
Defines a set of values for conditions that provide the information for determining the 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.
Use the proxy rules DTD to configure the proxy rules. The DTD file is available in the following location:
sps_home\secure-proxy\proxy-engine\conf\dtd
The following elements are configurable in DTD:
The nete:proxyrules is the mandatory root element in proxyrules.xml and has the following syntax:
<!ELEMENT nete:proxyrules (nete:description?,(nete:cond | nete:forward | nete:redirect | nete:local)) >
You can define an optional nete:description element and one of the following elements:
The debug attribute lets you manage logging and debug proxy rules. It has the following syntax:
<ATTLIST nete:proxyrules debug (yes|no) "no"
Set the value to yes to enable logging. The log file location is determined by the TraceFileName parameter in the agent configuration object that you configured for CA SiteMinder® SPS. The TraceConfigFile parameter in the same agent configuration object must point to the Secure Proxy-specific trace logging configuration file. By default, the file is located at <install-dir>\proxy-engine\conf\defaultagent\SecureProxyTrace.conf.
For example: <nete:proxyrules xmlns:nete="http://www.ca.com/" debug="yes">
The nete:description element 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.
It has the following syntax:
<!ELEMENT nete:description (#PCDATA)>
It can be a child of the nete:proxyrules element and may contain any description.
The nete:case element defines the destination associated with a specific value for a condition defined in the nete:cond parent element. CA SiteMinder® SPS uses the value of the nete:case element to evaluate a case.
It has the following syntax:
<!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:
Allows you to nest multiple conditions in a set of proxy rules.
Allows you to nest a regular expression condition in a set of other conditions.
Provides a destination to which requests that fulfill the nete:case comparison will be forwarded.
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 CA SiteMinder® 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. 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.
When forwarding or redirecting a request, CA SiteMinder® SPS uses a system for maintaining some part or all of the URI specified by a user. The URI points to a resource that lies on a destination server and must be interpreted to fulfill a request.
Either of the following may be appended to the URL specified in a forward or redirect destination:
Appends the entire URI string from the user 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.
Indicates that everything to the right of the matching text is appended to the forwarded or redirected request. Use it in nete:case elements where the parent nete:cond element specifies a URI substring match using the begins with comparison.
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: As the example specifies the $1 parameter, the /hr portion of the URI is omitted when the request is forwarded to hr.company.com.
The nete:cond element specifies a condition that is evaluated to determine how the incoming requests is handled. You must include an attribute that must be evaluated.
It has the following syntax:
<!ELEMENT nete:cond (nete:case+,nete:default)>
You can define the following attributes:
<!ATTLIST nete:cond type (header | host | uri | query | cookie) #REQUIRED criteria (equals | beginswith | endswith | contains | exists) "equals" headername CDATA #IMPLIED>
Specifies that an HTTP header is used to determine the destination of a request. You must define a header name too. Conditions that use headers as the comparison require an additional argument of headername="value", where value is the name of the HTTP or CA SiteMinder® header.
Note: HTTP headers generated by CA SiteMinder® responses may be specified in the nete:cond elements.
For example:
<nete:cond type="header" headername="USER_AGENT">
This element indicates that a header is used, and that USER_AGENT is the header to be evaluated.
Specifies a host name in deployments where multiple virtual hosts are used. 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.
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:
Specifies universal resource indicator that 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.
Specifies a cookie attribute to determine how to route a request. If a cookie value is encoded, specify the encoding scheme in encoding parameter. Only the base64 encoding scheme is supported and cookie creation is not supported. The following are the possible cases of an encoded cookie:
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:
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.
If no criteria are specified, equals is assumed the default criteria.
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.
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.
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.
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.
Each nete:cond element must have one or more nete:case child elements. The nete:case children provide the unique values that are used to route requests to appropriate destinations.
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 CA SiteMinder® 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.
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.
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.
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.
The nete:local element is included to support future functionality, and should not be included in proxy rules configuration files.
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.
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.
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 CA SiteMinder® 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 CA SiteMinder® 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.
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
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.
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:
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.
|
Characters |
Results |
|---|---|
|
unicode character |
Matches any identical unicode character |
|
\ |
Used to quote a meta-character like '*') |
|
\\ |
Matches a single ’\’ character |
|
\0nnn |
Matches a given octal character |
|
\xhh |
Matches a given 8-bit hexadecimal character |
|
\\uhhhh |
Matches a given 16-bit hexadecimal character |
|
\t |
Matches an ASCII tab character |
|
\n |
Matches an ASCII newline character |
|
\r |
Matches an ASCII return character |
|
\f |
Matches an ASCII form feed character |
|
[abc] |
Simple character class |
|
[a-zA-Z] |
Character class with ranges |
|
[^abc] |
Negated character class |
|
[:alnum:] |
Alphanumeric characters |
|
[:alpha:] |
Alphabetic characters |
|
[:blank:] |
Space and tab characters |
|
[:cntrl:] |
Control characters |
|
[:digit:] |
Numeric characters |
|
[:graph:] |
Characters that are printable and are also visible (A space is printable, but not visible, while an ‘a’ is both) |
|
[:lower:] |
Lower-case alphabetic characters |
|
[:print:] |
Printable characters (characters that are not control characters) |
|
[:punct:] |
Punctuation characters (characters that are not letter, digits, control characters, or space characters) |
|
[:space:] |
Space characters (such as space, tab, and formfeed) |
|
[:upper:] |
Upper-case alphabetic characters |
|
[:xdigit:] |
Characters that are hexadecimal digits |
|
[:javastart:] |
Start of a Java identifier |
|
[:javapart:] |
Part of a Java identifier |
|
. |
Matches any character other than newline |
|
\w |
Matches a "word" character (alphanumeric plus "_") |
|
\W |
Matches a non-word character |
|
\s |
Matches a whitespace character |
|
\S |
Matches a non-whitespace character |
|
\d |
Matches a digit character |
|
\D |
Matches a non-digit character |
|
^ |
Matches only at the beginning of a line |
|
$ |
Matches only at the end of a line |
|
\b |
Matches only at a word boundary |
|
\B |
Matches only at a non-word boundary |
|
A* |
Matches A 0 or more times (greedy) |
|
A+ |
Matches A 1 or more times (greedy) |
|
A? |
Matches A 1 or 0 times (greedy) |
|
A{n} |
Matches A exactly n times (greedy) |
|
A{n,} |
Matches A at least n times (greedy) |
|
A{n,m} |
Matches A at least n but not more than m times (greedy) |
|
A*? |
Matches A 0 or more times (reluctant) |
|
A+? |
Matches A 1 or more times (reluctant) |
|
A?? |
Matches A 0 or 1 times (reluctant) |
|
AB |
Matches A followed by B |
|
A|B |
Matches either A or B |
|
(A) |
Used for subexpression grouping |
|
\1 |
Backreference to 1st parenthesized subexpression |
|
\n |
Backreference to nth parenthesized subexpression |
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.
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.
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>
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>
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>
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.
To modify manually, edit the proxyrules.xml file using a text editor. Verify that the proxy rules configuration file must be well-formed and valid, and 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 proxyrules.xml file are picked up automatically. When a request is received, CA SiteMinder® SPS 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.
To modify using Administrative UI, perform one of the following steps:
Custom filters are filters defined by customer's needs. CA SiteMinder® SPS uses custom filters to manipulate a request before forwarding the request to a backend server, and also to manipulate the responses sent by the backend server to the user client.
To add filters in proxyrules.xml or text mode in the Admin UI, type the filter as required in the proxy rules.
Example:
<nete:forward filter="filter1"http://FQDN$0</nete:forward>
To add filters in the tree mode in the Admin UI, perform the following steps:
To apply a filter in the tree mode in the Admin UI, enter the name of the filter you want to apply when you create an action proxy rule.
You can validate the new proxy rules against the proxy rules DTD. The validation ensures that the new proxy rules are defined in the correct XML file configurations as per the DTD.
To validate the new proxy rules, click Validate in the Proxy rules page in any mode after you save the proxy rules.
You can test the proxy rules to verify their functionality.
Follow these steps:
You can export the new proxy rules through the Admin UI for future reference.
Follow these steps:
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
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.
|
Requested URL |
Forwarded URL |
|---|---|
|
http://banking.company.com/index.html |
http://server1.company.com/index.html |
|
http://bondtrading.company.com/index.html |
http://server2.company.com/index.html |
|
http://www.company.com/index.html |
http://home.company.com/index.html |
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.
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.
|
Requested URL |
Forwarded URL |
|---|---|
|
http://www.company.com/index.html HTTP_HEADER has the following value: HTTP_HEADER="value1" |
http://server1.company.com/index.html |
|
http://www.company.com/index.html HTTP_HEADER has the following value: HTTP_HEADER="value2" |
http://server2.company.com/index.html |
|
http://www.company.com/index.html HTTP_HEADER has a value other than value1 or value2. |
http://home.company.com/index.html |
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.
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.
|
Requested URL |
Forwarded URL |
|---|---|
|
http://www.company.com/index.html User access resource via a Web browser. |
http://home.company.com/index.html |
|
http://www.company.com/index.wml User access resource via a wireless device. |
http://wireless.company.com/index.wml |
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.
|
Requested URL |
Forwarded URL |
|---|---|
|
http://www.company.com/dir1/index.html |
http://server1.company.com/index.html |
|
http://www.company.com/dir2/index.html |
http://server2.company.com/index.html |
|
http://www.company.com/index.html |
http://home.company.com/index.html |
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.
|
Requested URL |
Forwarded URL |
|---|---|
|
http://www.company.com/app.jsp |
http://application.company.com/app.jsp |
|
http://www.company.com/index.wml |
http://wireless.company.com/index.wml |
|
http://www.company.com/index.html |
http://home.company.com/index.html |
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.
|
Requested URL |
Forwarded URL |
|---|---|
|
http://banking.company.com/index.wml |
http://wireless.company.com/banking/index.wml |
|
http://banking.company.com/index.html |
http://server1.company.com/banking/index.html |
|
http://bondtrading.company.com/index.html with a header value of GOLD_USER="yes" |
http://fast.company.com/bondtrading/index.html |
|
http://bondtrading.company.com/index.html with a header value of GOLD_USER="no" |
http://server2.company.com/bondtrading/index.html |
|
http://www.company.com/index.wml with a USER_AGENT header value that contains a wireless device name |
http://home.company.com/ |
|
http://www.company.com/index.html with a USER_AGENT header value that does not contains a wireless device name |
http://home.company.com/index.html |
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.
|
Requested URL |
Forwarded URL |
|---|---|
|
http://server.company.com/realma/hr/index.html |
http://server1.company.com/hr/index.html |
|
http://server.company.com/GOTO=server2.company.com/index.html |
http://server2.company.com/index.html |
|
http://server.company.com/REDIR=server2.company.com/index.html |
http://server2.company.com/index.html User is redirected so that |
|
http://server.company.com/index.html |
http://www.company.com/index.html |
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.
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.
|
Copyright © 2014 CA Technologies.
All rights reserved.
|
|