WEB-INF/proxy-config.xml file


The proxy-config.xml file defines the policy by which URI requests are supported to pass through the proxy and how context paths from the client are mapped to the URI on a server.

You can modify the proxy-config.xml file with a text editor. Save this file in a location on the class path that the proxy servlet can locate. Changes to the proxy-config.xml file are not dynamic; restart the servlet for the changes to take affect.

Example usage

Consider a JavaTM Platform, Enterprise Edition (Java EE) enterprise archive file (EAR) which contains your Ajax-based application. You are using the Dojo toolkit to combine content that orginates from another server and provides location information of coffee houses. The data format is returned from another server as JavaScriptTM Object Notation (JSON) data. Combine the JSON data returned with the Ajax-based application you are developing, which is often referred to as a client-side mashup.

Enter the following lines of code: 

GET http://www.myinformation.com/location/coffee  HTTP/1.1
The following JSON content is returned: 
{
   "locations":{
      "location":[
         {
            "id":"Jumpin Joes Example",
            "city":"Anywhere",
            "location":"Weston Pkwy",
            "address":"126 Weston Pkwy, Anywhere, NC 27513",
            "date":"May 2nd, 2008"
         },
         {
            "id":"Coffee & Crepes Example",
            "city":"Anywhere",
            "location":"Crossroads Blvd",
            "address":"123 Crossroads Blvd, Anywhere, NC 27518",
            "date":"May 3rd, 2008"
         } ]
   }
}

By using the Ajax proxy, you can make the service available by adding the following lines of code to your proxy-config.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<proxy-rules xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:proxy="http://www.ibm.com/xmlns/prod/websphere/featurepack/v6.1/proxy-config" xsi:noNamespaceSchemaLocation="C:\temp\proxy-config.xsd">  
        <proxy:mapping contextpath="/location/coffee" url="http://www.myinformation.com"/>
        <proxy:policy url="*" acf="none">
                <proxy:actions>
                        <proxy:method>GET</proxy:method>                    
                </proxy:actions>
                
        </proxy:policy>
</proxy-rules>

The contextpath above is the context root of the service that is being accessed. The URL is the root URL to the service. As an example, you could access the service directly in a browser by using http://www.myinformation.com/location/coffee

The path to access the proxy within your code is dependent on how the Ajax proxy has been deployed. Consider the fragment of XML from a web.xml that may be used for the Ajax proxy:

	<servlet-mapping>
		<servlet-name>ProxyServlet</servlet-name>
		<url-pattern>/proxymashup/*</url-pattern> 		
	</servlet-mapping>
In the above example, the ProxyServlet is the servlet for the Ajax proxy. The <url-pattern> is the servlet mapping to /proxymashup/*. If the context root of the Web application archive (WAR) file is /proxy then you would use the following code to access the service using Dojo: 
var deferred = dojo.xhrGet( {
                             url: "/proxy/proxymashup/location/coffee",
                             timeout: 5000,            
                             handleAs : "text/json",
                             headers: { "Content-Type":"text/html" },          
                             } );

XML schema

The XML schmeas for the proxy-config.xml file are located in the WEB-INF/ directory for the AjaxProxy.war file. The two schemas are proxy-config_1.0.1.xsd and proxy-config_1.0.xsd. The proxy-config_1.0.1.xsd corresponds to the 1.0.1 version and contains new features such as IP Filtering. Users can continue to use prior versions of the proxy-config.xml which correspond to the proxy-config_1.0.xsd.

Filtering MIME types

The Multipurpose Internet Mail Extensions (MIME) type controls the media types that are accepted from the service to the proxy. In the previous example, if you want to ensure that only text/json content type is returned to the client, you can add the following entry to the proxy-config.xml file: 
<proxy:policy url="*" acf="none">
    .
    .
    <proxy:mime-types>
       <proxy:mime-type>text/json</proxy:mime-type>
    </proxy:mime-types>
    .
    .
</proxy:policy>

If the service returned text/html, the proxy responds by returning an error condition to the client since the text/html is not listed as an acceptable content type from the server. If the <proxy:mime-types> is not specified, the behavior is to allow all content types.

Filtering cookies

You can use the Ajax proxy to control the flow of cookies to the client by specifying a cookie policy. Only cookies that match the value in the cookie policy will be allowed to pass through the Ajax proxy. If no cookie policy is specified, then NO cookie is allowed to pass through the Ajax proxy.

To control the flow of cookies, define the allowed cookie name in the proxy-config.xml file. The following example shows how you can configure the proxy to only pass cookies that have the cookie key name of Session-Cookie-0.

<proxy:policy url="*" acf="none">
    .
    .
    <proxy:cookies>
       <proxy:cookie>Session-Cookie-0</proxy:cookie>
    </proxy:cookies>
    .
    .
</proxy:policy>

Filtering HTTP headers

By default, the Ajax proxy allows the following HTTP headers to be passed to the client: User-Agent, Accept*, Content*, Authorization*. The (*) represent wildcards. All other headers are dropped by the Ajax proxy before passing along the request to the service. Typically, these headers are sufficent for most applications. You can define your own set of allowed HTTP headers by inserting the following configuration into the proxy configuration file: 
<proxy:policy url="*" acf="none">
    .
    .
    <proxy:headers>
       <proxy:header>User-Agent</proxy:header>
       <proxy:header&gtAccept*</proxy:header>     
       <proxy:header>Content*</proxy:header>
       <proxy:header>Authorization*</proxy:header>
       <proxy:header>My-New-Header</proxy:header>
       <proxy:header>My-Other-New-Header</proxy:header>                       
    </proxy:headers>
    .
    .
</proxy:policy>

Filtering HTTP methods

In the previous example, the Ajax proxy is configured to only accept GET requests from the client. A POST or other HTTP method request returns an error condition to the client. The Ajax proxy supports GET, POST, PUT, HEAD, or DELETE requests. You must specify at least one supported HTTP method.

Support for SSL

A number of services might require a secure socket connection that uses SSL. As a Web application, the Ajax proxy leveages the JavaTM Secure Socket Extension (JSSE) and is fully supported by the product. Consult the corresponding WebSphere® documentation on SSL certificate support.

Using unsigned SSL certificates

By default, the Ajax proxy does not support unsigned certificates. Instead, you receive an SSL exception with the message Unrecognized SSL handshake. If you require unsigned SSL certificates for testing or development, then you can enable the following option in the proxy-config.xml file: 
    <proxy-meta-data>
        <proxy:name>unsigned_ssl_certificate_support</proxy:name>
        <proxy:value>true</proxy:value>
    </proxy-meta-data>

When unsigned_ssl_certificate_support is enabled, the Ajax proxy accepts any SSL certificate. In practice, this setting is used for development and should not be used in a production environment.

Configuration Options

The Ajax proxy can be tuned with a number of parameters.

maxconnectionsperhost

The maxconnectionperhost is a global value that specifies the maximum number of connections kept alive for any host or port combination. By default, the value is set to 2. Increase the value if your application accesses more than two remote sites for content. 

<proxy:meta-data>
   <proxy:name>maxconnectionsperhost</proxy:name>
       <proxy:value>2</proxy:value>
</proxy:meta-data>

maxtotalconnections

The maxtotalconnections is the maximum total of connections supported by the proxy. The default value is 5. The value you choose must be a high enough to support the number of simultaneous connections you might receive. In practice, factor in how the Web container is configured and how many simultaneous connections the container supports. 

<proxy:meta-data>
   <proxy:name>maxtotalconnections</proxy:name>
   <proxy:value>5</proxy:value>
</proxy:meta-data>

socket-timeout

The socket-timeout defines the default socket timeout in milliseconds for waiting for data once a connection has been established. The default is a timeout value of 0 which is interpreted as an infinite timeout.

<proxy:meta-data>
   <proxy:name>socket-timeout</proxy:name>
   <proxy:value>5000</proxy:value>
</proxy:meta-data>

retries

The retries defines the number of socket retries the Ajax proxy should perform before giving up on establishing a connection. The default value is two retries. 

<proxy:meta-data>
   <proxy:name>retries</proxy:name>
   <proxy:value>3</proxy:value>
</proxy:meta-data>

connection-timeout

The connection-timeout defines the time in milliseconds before a connection is established. If no value is specified, then the default value of 60000 is used. If 0 is used, then the value is interpreted to mean no timeout is used. 

<proxy:meta-data>
   <proxy:name>connection-timeout</proxy:name>
   <proxy:value>3000</proxy:value>
</proxy:meta-data>

connection-pool-timeout

The connection-pool-time defines the time in milliseconds before attempting a connection. This is the case for all subsequent requests after maxtotalconnections is exceeded. If 0 is used, then the value is interpreted to mean no timeout is used. 0 is also the default value. 

<proxy:meta-data>
   <proxy:name>connection-pool-timeout</proxy:name>
   <proxy:value>1000</proxy:value>
</proxy:meta-data>

forward-http-errors

By default, the Ajax proxy will only forward HTTP status codes greater than or equal to 200 and less than 400. Status codes that fall outside the range automatically change to a 404 File Not Found error. The only exception is code 401 (unauthorized), which results in 403 Forbidden unless the basic-auth-support attribute is enabled for that specific request.

You can forward HTTP codes greater than or equal 400 with a message by setting the forward-http-errors meta parameter in the proxy-config.xml 

<proxy:meta-data>
   <proxy:name>forward-http-errors</proxy:name>
   <proxy:value>true</proxy:value>
</proxy:meta-data>

Connecting to another proxy

The Ajax proxy can be configured to connect to another proxy before accessing the network. Connection to a pass-thru proxy might be required if the Ajax proxy needs to go through a border firewall before accessing the network. The Ajax proxy supports Basic authentication.

The following example shows the configuration for a fictitious proxy firewall. The passthru_host is a required parameter. Others like passthru_type, passthru_username, and passthru_password are optional parameters. The passthru_type parameter signifies type of authentication used. The default type is BASIC. Alternately, DIGEST and NTLM can be used as well. NTLM requires additional paramters passthru_hostname and passthru_domain. The passthru_port and passthru_realm parameters are also optional. If a passthru_port parameter is not specified, then a default value of port 80 is used. If a passthru_realm parameter is not specified then the credentials are sent for all authentication attempts. Specify the passthru_realm parameter in a production environment to prevent the user name and password information from being presented for all authentication requests. 

	<proxy-meta-data>
       <proxy:name>passthru_type</proxy:name>        
       <proxy:value>BASIC</proxy:value>
     </proxy-meta-data>
    <proxy-meta-data>
       <proxy:name>passthru_host</proxy:name>        
       <proxy:value>9.17.237.132</proxy:value>
     </proxy-meta-data>  
    <proxy-meta-data>
       <proxy:name>passthru_port</proxy:name>        
       <proxy:value>3128</proxy:value>
     </proxy-meta-data> 
    <proxy-meta-data>
       <proxy:name>passthru_realm</proxy:name>        
       <proxy:value>MyRealm</proxy:value>
     </proxy-meta-data>
    <proxy-meta-data>
       <proxy:name>passthru_username</proxy:name>
       <proxy:value>username</proxy:value>
     </proxy-meta-data>       
    <proxy-meta-data>
       <proxy:name>passthru_password</proxy:name> 
       <proxy:value>password</proxy:value>
    </proxy-meta-data>

Enabling Basic Authentication

Basic authentication can be enabled by setting the basic-auth-support attribute for a policy in the proxy-config.xml. As an example: 

<proxy-rules
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1">
 <proxy:mapping contextpath="/proxy/*" />

 <proxy:policy url="*" acf="none" basic-auth-support="true">
    <proxy:actions>
       <proxy:method>GET</proxy:method>
    </proxy:actions>
 </proxy:policy>
</proxy-rules>

In the example, the Ajax proxy will forward HTTP status and header information back to the target service and client. If the basic-auth-support is not set and the Ajax proxy receives a 401 request, the proxy will map the request to a 403 : Forbidden HTTP code.

Note: Currently, the Basic Authentication mechanism is the only HTTP authentication method supported by the proxy.

Filtering IP addresses

The Ajax proxy's IP Filtering allows you to white-list or blacklist IP addresses in order to protect services the Ajax proxy may connect too. The blacklist contains service IP addresses that clients are not allowed to connect too while the white-list contains IP addresses of services that the Ajax proxy can connect too.

The proxy:ipfilter defines the IP addresses to filter. The proxy:allow defines the white-list for an IP address or range of addresses. The proxy:deny defines a blacklist of IP address or range of addresses.

For example: 
<proxy-rules
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1">
 <proxy:mapping contextpath="/proxy/*" >
 
    <proxy:ipfilter>
         <proxy:deny>9.6.0.0/255.255.0.0</proxy:deny>
         <proxy:allow>9.6.1.0/255.255.255.0</proxy:allow>
         <proxy:deny>9.6.1.4</proxy:deny>
    </proxy:ipfilter>
 
 </proxy:mapping>
 
 <proxy:policy url="*" acf="none">
         <proxy:actions>
                 <proxy:method>GET</proxy:method>
         </proxy:actions>
 </proxy:policy> 
</proxy-rules>

In this example, the Ajax proxy filters on the following: So, in this case, the proxy would not allow access to IP address 9.6.2.5 or 9.6.120.7 and would respond with the following message: 
CWXJX1000E: The specified target hosts IP-address is prohibited by rule.

However, the Ajax proxy would access to 9.6.1.5 or 9.6.1.120 but would deny access to 9.6.1.4.

Another example that starts by blacklisting all IP addresses, but adds additional IP ranges. In this example, the following code element blocks all IP addresses: *.*.*.*. IP address in the range of 98.137.80.1 to 98.137.254 are supported. 

<proxy-rules
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:proxy="http://www.ibm.com/xmlns/prod/sw/ajax/proxy-config/1.1">
 <proxy:mapping contextpath="/rss/economy" url="http://rss.news.yahoo.com">
 
     <proxy:ipfilter>
         <proxy:deny>*.*.*.*</proxy:deny>         
         <proxy:allow>98.137.80.0/255.255.255.0</proxy:allow>         
    </proxy:ipfilter>
 </proxy:mapping>
 
 <proxy:policy url="*" acf="none">
         <proxy:actions>
                 <proxy:method>GET</proxy:method>
         </proxy:actions>
 </proxy:policy> 
</proxy-rules>

As you add new filter rules, you can combine them in a number of ways, but the Ajax proxy always handles them in the order in which they are defined. This means that the last matching rule will always take effect, regardless of any allow and deny rules that come before it.

Terms of Use | Feedback