Configure Proxy Rules Manually

Contents
casso126
Contents
3
CA Access Gateway
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.
CA Access Gateway
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 Access Gateway
records the error in the server log that is configured in the logger.properties file, ignores the changes, and uses the existing proxy rules.
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.
Planning Routes for Incoming Requests
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 Access Gateway
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.
Designing proxy rules
Designing proxy rules
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:
Designing proxy rules with nested conditions
Designing proxy rules with nested conditions
Proxy Rules Terminology
The following terms are used to describe the proxy rules:
  • Destinations
    Defines a destination URL that fulfills a request.
    CA Access Gateway
    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
    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:
    • URI
      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.
    • Query String
      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.
    • Host
      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.
    • Header
      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.
      HTTP headers derived from
      CA Single Sign-On
      responses may be used to determine how to route a request.
    • Cookie
      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.
  • Cases
    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.
Proxy Rules DTD
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:
  • nete:proxyrules
  • nete:description
  • nete:case
  • nete:cond
  • nete:default
  • nete:forward
  • nete:redirect
  • nete:local
  • nete:xprcond
nete proxyrules
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:
  • nete:cond
  • nete:xprcond
  • nete:forward
  • nete:redirect
  • nete:local
Debug Attribute
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 Access Gateway
. 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">
nete description
The nete:description element is an optional element that contains a parsed character data (PCDATA) description of another element.
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.
nete case
The nete:case element defines the destination associated with a specific value for a condition defined in the nete:cond parent element.
CA Access Gateway
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:
  • nete:cond
    Allows you to nest multiple conditions in a set of proxy rules.
  • nete:xprcond
    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
    CA Access Gateway
    .
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>
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 Access Gateway
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,
CA Access Gateway
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:
  • $0
    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 requests for www.company.com/employees/hr/index.html, that request is forwarded to proxy.company.com/employees/hr/index.html.
  • $1
    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:
    The request is forwarded to:
    As the 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 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>
  • header
    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 Single Sign-On
    header.
    HTTP headers generated by
    CA Single Sign-On
    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.
  • host
    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.
  • 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 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.
    • 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. Only the base64 encoding scheme is supported and cookie creation is not supported. 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 base64 encoding algorithm is used to decode the cookie value received from a httprequest and the result of the decoded value is compared 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 specified plain text is accepted as the cookie value and the nete:cond is verified.
      • 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 specified encoded cookie value is accepted as plain text, and the plain text cookie value is used 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.
    If no criteria are specified, equals is assumed the default criteria.
  • 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.
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.
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
CA Access Gateway
.
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 Access Gateway
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 Access Gateway
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.
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 Access Gateway
to a destination server. Filters can be written using the Filter API.
Filter Attribute
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 Access Gateway
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 Access Gateway
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 Access Gateway
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 Access Gateway
is removed from the transaction, and the destination server provides resources directly to the user.
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
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.
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 Access Gateway
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 Access Gateway
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
CA Access Gateway
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 Access Gateway
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 Access Gateway
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
Response Handling
The
CA Access Gateway
uses
CA Single Sign-On
responses to determine a destination for a request. Since transactions that are routed through the
CA Access Gateway
include an interaction between the
CA Access Gateway
web agent and
CA Single Sign-On
, any
CA Single Sign-On
responses gathered during the authentication and authorization process may be used by the
CA Access Gateway
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 Access Gateway
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.
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 Access Gateway
processes requests, and it encounters a nete:xprcond element in the proxy rules configuration file, the following occurs:
  1. The
    CA Access Gateway
    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 Access Gateway
    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.
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 Access Gateway
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 Access Gateway
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 Access Gateway
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 Access Gateway
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 Access Gateway
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 Access Gateway
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>
The service attribute instructs the
CA Access Gateway
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
CA Single Sign-On
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.
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:
You can use multiple headers in a single nete:forward element. For example:
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:
You can use multiple headers in a single nete:redirect element. For example:
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:
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 Access Gateway
uses
CA Single Sign-On
responses to determine a destination for a request. Since transactions that are routed through the
CA Access Gateway
include an interaction between the
CA Access Gateway
web agent and
CA Single Sign-On
, any
CA Single Sign-On
responses gathered during the authentication and authorization process may be used by the
CA Access Gateway
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 Access Gateway
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 Manually
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 Access Gateway
checks whether or not the proxy rules have changed. If the file has changed, the rules are reloaded before fulfilling the request.
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 Access Gateway
.
Sample Proxy Rules Configuration Files
The
CA Access Gateway
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 Access Gateway
requests based on the hostname specified in the request,
CA Access Gateway
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 Access Gateway
, 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.
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.
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
 
Proxy Rules Example -- Routing Requests by Header Value
The example file proxyrules_example2.xml file routes
CA Access Gateway
requests based on the value of an HTTP header. The HTTP header can be a standard header or one created using a
CA Single Sign-On
response.
In this example, assume that the
CA Access Gateway
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
You do not need to include the HTTP_ of the header variable name in the nete:cond element.
CA Access Gateway
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 Access Gateway
requests based on the type of device used to access the resource.
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
 
Proxy Rules Example -- Routing Requests with URIs
The example file proxyrules_example4.xml file routes
CA Access Gateway
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
 
Proxy Rules Example -- Routing Requests by File Extension
The example file proxyrules_example5.xml file routes
CA Access Gateway
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 Access Gateway
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
 
Proxy Rules Example -- Routing Requests with Nested Conditions
The example file proxyrules_example6.xml file routes
CA Access Gateway
requests based on the hostname, certain headers, and device types. This file demonstrates how the
CA Access Gateway
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 Access Gateway
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/
wireless/index.wml
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
 
Proxy Rules Example -- Using Regular Expression in Proxy Rules
The example file proxyrules_example7.xml file routes
CA Access Gateway
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 Access Gateway
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
server2.company.com must directly fulfill the user’s request.
http://server.company.com/index.html
http://www.company.com/index.html
 
Proxy Rules Example -- Routing Requests by Cookie Existence
The example file proxyrules_example8.xml file routes
CA Access Gateway
requests based on the existence of a cookie.
In this example, if a request contains a cookie header "mycookie",
CA Access Gateway
routes the request to www.company.com.
Proxy Rules Example -- Routing Requests by Cookie Value
The example file proxyrules_example9.xml file routes
CA Access Gateway
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 Access Gateway
routes the request to www.abcd.com. If a request contains a cookie header "mycookie" and the base64 encoding mechanism,
CA Access Gateway
routes the request to www.xyz.com.