Using the proxy page

The ArcGIS JavaScript API provides a proxy page that you may use to handle communication with the ArcGIS Server services you use in your application. The proxy page consists of server-side code that runs on your Web server. The browser sends the request to your proxy, and your proxy in turn forwards the request to the ArcGIS Server service.

You may wish to use the proxy page in your application in either or both of these two situations:

• The application creates requests that exceed the limit on the length of URLs imposed by the browser. A common situation would be when the application creates buffers around complex polygons, and then sends the buffer polygons to select features with the QueryTask. The geometry of the buffer may consume more than the URL limit, and the application will fail. Some modern browsers restrict URLs with more than about 2000 characters.
• The application uses a service that is secured with token-based authentication, and you do not wish to allow users to view the token, or you do not want to transmit the token over the network between your Web server and your users.

To handle these situations, your application can have client browsers send service requests to the proxy page running on your Web server. Your proxy page then sends the requests to the ArcGIS Server service. In the first case above, the application only needs to use the proxy when the URL length exceeds 2000 characters. In the second case, the proxy page is always used. Since the proxy requires extra time and resources on your server, you should use the proxy page only when your application requires it.

To use the proxy page, you need to perform the following steps. These are described in detail below.

1. Download and configure the proxy page appropriate for your server
2. Add code to your application page to enable use of the proxy
3. Secure the Web application, especially when using a service with token-based authentication
4. Test to ensure the proxy is working correctly

Step three is critical for applications that use tokens. If you do not secure the application correctly, then the ArcGIS Server services used by the application are vulnerable to unlimited use by unauthorized persons. See the section on securing the application below for further information.

Here are some technical details on the proxy page for interested readers. In the first situation described earlier, with lengthy URLs, the proxy page allows the browser to perform a POST request rather than the GET request that the browser would normally do with service requests. A POST request does not have the same relatively low limit on amount of data sent as does a GET request. However, for security reasons, browsers are not allowed to POST except back to the server that sent the page to the browser. Hence the proxy page must run on the same Web server where your application runs. In the second situation, the authentication token is configured in the proxy page, rather than in the HTML page downloaded by the client. The browser sends a request (by either GET or POST) to the proxy page. The proxy page then appends the token to the request and forwards the request to the ArcGIS Server computer, then returns the response to the browser. This way, the end user does not have access to the token. This can provide enhanced security for the ArcGIS Server service, provided that the security measures described later in this page are implemented.

1. Download and configure the proxy page

You must download the proxy page and include it in your Web application. The proxy page runs on your local Web server, not on an ESRI server or on the ArcGIS Server computer (unless your Web server also hosts the ArcGIS Server instance). Three proxy pages are available, each running on a specific server-side platform: ASP.NET, Java/JSP, and PHP. Your Web server must support one of these server-side platforms in order to use the proxy page. Download the appropriate page for your platform.

• For ASP.NET: proxypage_net.zip (contains proxy.ashx and proxy.config)
• For Java/JSP: Download proxypage_java.zip (contains proxy.jsp and web.xml)
• For PHP: Download proxypage_php.zip (contains proxy.php)

Unzip and save the proxy page to your Web application's folder. Then configure your application or server so that it will run the proxy page.

• For ASP.NET, ensure that ASP.NET, version 2.0 or higher, is installed on your server and is registered with your Internet Information Services (IIS) Web server. For Windows Server 2003, ensure that ASP.NET is allowed on the server. See this page at Microsoft or other resources for configuring ASP.NET on your server. The folder for your application does not need to allow script execution, as long as the root Web site is configured for ASP.NET.
• For Java/JSP, unzip the zip file into your Java Web Application Server's web applications directory (for Tomcat, this would be the webapps directory under the base Tomcat folder).
• For PHP, unzip the file into the Web applications directory. For Apache installs of PHP, this would be a folder under "htdocs" in the Apache install location. For IIS installs, this would be a folder under "wwwroot".

Configure the proxy page for the token.

For ASP.NET:

1. If you will be using the proxy page for services with token-based authentication, obtain a token for the service. See instructions at Working with secure ArcGIS services. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.
2. Open the configuration proxy page (proxy.config for ASP.NET) in a text or XML editor.
3. For each ArcGIS Server that will use the proxy page, add a <serverUrl> entry to the configuration XML file within the <serverUrls> section. See the proxy configuration file for examples. The serverUrl element can have these attributes:
   • url: the URL of the ArcGIS Server machine or the service. If multiple services in the same server are used in the application, then the url can point to the services root. If only a single service on the server is used, then the url can be set to the full service URL.
   • matchAll: whether to use the token for all requests with this URL stem. If this attribute is true and the url attribute is set to the services root, then the entry can be used for multiple services in the application.
   • token: the authentication token obtained in step 1. Optional - used only for services secured with token-based authentication.
   If multiple services on the same server are used in the application, the URL may point to the service root (e.g., http://www.example.com/arcgis/rest/services), and the matchAll parameter set to true. See commented examples included in the downloaded file. Multiple server entries may be added if more than one ArcGIS Server computer is used in the application.
4. Save the configuration file.

Examples

• The service is at http://www.example.com/arcgis/rest/services/MyMapService/MapServer, and the proxy is used because of lengthy requests sent in queries, then the element may be set to:
  
  <serverUrl url="http://www.example.com/arcgis/rest/services/MyMapService/MapServer" matchAll="false" ></serverUrl>
  
• Two services are used on the same server: http://www.example.com/arcgis/rest/services/MyMapService/MapServer and http://www.example.com/arcgis/rest/services/MyGPService/GPServer. Neither service requires a token, and the proxy is used because of lengthy requests. The serverUrl element would be:
  
  <serverUrl url="http://www.example.com/arcgis/rest/services" matchAll="true" ></serverUrl>
  
  Alternatively, two serverUrl elements may be added, one for each service, as in the first example.
  
• The service is a secured service at https://www.example.com/arcgis/rest/services/MyMapSecureService/MapServer. A token is obtained from the server's token service and added to the entry.
  
  <serverUrl url="https://www.example.com/arcgis/rest/services/MyMapSecureService/MapServer" matchAll="false" token="5fFo4%2fI4Tv8IGSqSYbpUNORRD%2fYxXMSPo6NEHNNGMpt9CMknpXIjEVqYGm3uuQnU" ></serverUrl>

The mustMatch attribute in the containing <ProxyConfig> element controls whether only specified sites may be proxied. This attribute should generally be set to true. If set to false, then the proxy page will forward any request to any server. This could potentially allow your proxy page to be used to send requests to third-party servers without your permission.

For Java/JSP:

1. If you will be using the proxy page for services with token-based authentication, obtain a token for the service. See instructions at Working with secure ArcGIS services. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.
2. Open the configuration proxy page (proxy.jsp) in your favorite editor.
3. The JSP code defines a serverUrls variable. This represents the servers for which you want this JSP to act as a proxy. It is a String array where each String has the following syntax: "<url>,<token>". The token is optional. Add URLs to the services you want to access over here.
   See commented examples included in the JSP. Multiple server entries may be added if more than one ArcGIS Server computer is used in the application.
   Note that while this sample proxy includes the configuration in the JSP itself, you may want to configure the URLs in a separate resource file and have your application reference that file.
4. Save the JSP.

For PHP:

1. If you are using the proxy page for services with token-based authentication, obtain a token for the service. See instructions at Working with secure ArcGIS services. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.
2. Open the proxy page (proxy.php) in your favorite editor.
3. Using the "mustMatch" variable, specify whether the proxy should forward requests only to specified servers. If this value is true, the proxy will only forward requests to the servers specified in the "serverUrls" variable (see below). If this value is false, then the proxy will forward requests to any server - be warned that this could potentially allow your proxy page to be used to send requests to third-party servers without your permission.
4. Using the "serverUrls" variable, specify the servers that this proxy will forward requests to if "mustMatch" is true. It is an array where each element configures an ArcGIS server or service using an array with keys named "url", "matchAll" and "token". The sematics of these keys are similar to the correspondingly named attributes used in the ASP.NET proxy.
5. Save the PHP file.

All users: for services with token-based authentication, the URL of the service should use HTTPS, for example, https://www.example.com/arcgis/rest/services/MyMapService/MapServer. This ensures that the token appended to the query string of the request is encrypted and cannot be intercepted and used by unauthorized parties. This would be especially important when the communication between your Web server and the ArcGIS Server service travels over the Internet, and not just on the local network.

2. Add code to use the proxy page

In order for your application's page to send requests through the proxy, you must add code to the page as follows. In the startup function (e.g., OnPageLoad) in the JavaScript code of your page, add a line to set the proxy page. The following example is for the ASP.NET version; substitute proxy.jsp or proxy.php as appropriate. If your proxy page is not in the same directory as the Web application, adjust the path appropriately. The path should use a relative URL (e.g., ../proxy.ashx), or a URL relative to the root (e.g., /Proxy/proxy.ashx).

If you are using version 1.2 or lower, replace "esri.config" in the examples below with "esriConfig".

For ASP.NET:

esri.config.defaults.io.proxyUrl = "proxy.ashx";

(Note: if you are using version 1.2 or lower, the syntax would be esriConfig.defaults.io.proxyUrl = "proxy.ashx";

For Java/JSP:

esri.config.defaults.io.proxyUrl = "proxy.jsp"; //relative - if proxy.jsp is in the same application as the web page

Or

esri.config.defaults.io.proxyUrl = "http://samedomain:sameport/proxy/proxy.jsp"; //absolute - if proxy.jsp is in another application in the same domain

For PHP:

esri.config.defaults.io.proxyUrl = "proxy.php"; //relative - if proxy.php is in the same application as the web page

Or

esri.config.defaults.io.proxyUrl = "http://samedomain:sameport/proxy/proxy.php"; //absolute - if proxy.php is in another application in the same domain

Only if you are using the page with a service secured with tokens: add a statement to use the proxy for every request. Do not add this line if you only need to use the proxy when requests exceed the browser's limit on URL size (see above). If you add this line, the esriConfig.defaults.io.proxyUrl property must also be set.

esri.config.defaults.io.alwaysUseProxy = true;

If the alwaysUseProxy property is false (the default), the the proxy page will be used automatically if the Proxy property is set and the request exceeds 2000 characters.

3. Secure the Web application

This step is essential if the application uses services with token-based security, and the proxy page is configured with the token. If you do not secure the Web application, then anyone can send any request through your proxy page to the ArcGIS Server service, without using your application page. Your proxy page could be used for unauthorized disclosure of data from the service, or for inappropriate or high volume of use of the service.

To secure the Web application, you need do both of the following:

1. Require users of the application to login (authenticate) in order to use the application. This ensures that only authorized users can use the application, including the proxy page. How you require authentication depends on the type of server software you are using. For IIS/ASP.NET servers, you may use Windows authentication or ASP.NET forms; see this page at Microsoft for information and instructions. For other platforms, consult documentation on implementing authentication for your platform.
   -- and --
2. Require use of HTTPS via Secure Sockets Layer (SSL). At minimum the login page should be secured, especially if using forms or Basic authentication. For maximum security, you may require HTTPS for all communication in the application. Note that in order to require HTTPS for an application, you must obtain and install a SSL certificate for your Web server. If using IIS, the Microsoft documentation for IIS describes how to obtain and install SSL certificates.

4. Test and deploy the application

Once you have configured the proxy page with the application, test the application to ensure that requests are processed correctly. The application should function normally as it did before the proxy page was implemented. If not, you may need to troubleshoot the proxy. If your application environment supports debugging mode, you may be able to set breakpoint in the proxy page and detect whether it is operating correctly.

For example, in an IIS/ASP.NET environment, you can open the application in Visual Studio or Visual Web Developer Express, open the proxy.ashx page, and set a break point in the ProcessRequest method. Then run the application with Debug-Start. The execution should halt at the break point, and you should be able to detect where the problem lies. You may also be able to set break points in the JavaScript functions of your application, or insert alert() statements to display values during execution. As a last resort, remove the esriConfig.defaults.io.proxyUrl property value and start over.