Using the proxy page

The ArcGIS JavaScript API provides a proxy page that handles communication with the ArcGIS Server services you use in your application. The proxy page consists of server-side code that you set up to run on your Web server. The browser sends a request to the proxy and the proxy forwards the request to the ArcGIS Server service.     

        A proxy page is necessary in the following situations:       

•  The application creates requests that exceed 2048 characters. While there is no official maximum length for a URL some modern browsers have imposed limits. Using a proxy works around this issue by performing a POST request rather than a GET request. POST requests are not limited by the 2048 character maximum because the information is transferred in the header instead of the URL. Common situations where you may exceed the URL length are:           
  • Buffer complex polygons then use the buffered geometry with a query task.
  • Specify a spatial reference using well-known text (wkt).
•  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.         
•  The application edits features in a feature service, unless the application is on the same domain as the GIS Server.         

Install and Configure the proxy page

        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. This step is critical for applications that use tokens. If the application is not secured correctly, 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.       
4. Test to ensure the proxy is working correctly       

        1. Download and configure the proxy page     

        In this step, you'll learn how to download and install the proxy page on your Web server. 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). ESRI provides proxy pages for three languages (ASP.NET, Java/JSP, PHP), but you can create a proxy page in another language as well. Download and configure the appropriate proxy for your platform.     

        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.     

ASP.NET

       Before proceeding ensure, that you have ASP.NET 2.0 or higher installed and registered with Internet Information Services (IIS). If ASP.NET is not configured with IIS, follow the instructions for the version of IIS you are running in the ASP.NET and IIS Configuration help topic on MSDN.       

1. Download proxypage_net.zip, then unzip and save the contents to a folder on your web server's root directory. In IIS, the default location for the Web server's root folder is c:\inetpub\wwwroot. If you plan on using the proxy for multiple sites you can create a folder in the web root directory called proxy and place the contents there.
2. Unzip and save then contents to your Web server.
3. Open IIS Manager. This Microsoft Knowledge Base article provides instructions for opening IIS Manager depending on the version of IIS you are using.
4. Next, create a Web Application for the proxy folder, these steps also differ depending on the version of IIS you are using. For IIS 5 or 6 use the following steps:           
   1. In the Default Web Site, right-click the proxy directory and select Properties.
   2. On the Directory tab, in the Application Settings section click the Create button then click OK
5. 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.
6. Open the configuration proxy page (proxy.config for ASP.NET) in a text or XML editor.
7. 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 servicesin 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.

   The  mustMatch  attribute in the containing 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.

8. Save the configuration file.       

Java/JSP

1. Download proxypage_java.zip, then unzip and save the contents to your web server's web applications directory. For Tomcat, this is the webapps directory under the base Tomcat folder.
2. 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.       
3. Open the configuration proxy page (proxy.jsp) in your favorite editor.       
4. 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.         
5. Save the JSP.         

PHP

1. Download proxypage_php.zip, then unzip and save the contents to your web server's web applications directory. For Apache installs of PHP, this is a folder under htdocs in the Apache install location. For IIS installs, this is a folder under wwwroot.
2. If you are using the proxy page for services with token-based authentication, obtain a token for the service. See instructions atWorking with secure ArcGIS services. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.       
3. Open the proxy page (proxy.php) in your favorite editor.       
4. 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.       
5. 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.       
6. Save the PHP file.       

        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).     

Note: If you are using version 1.2 or lower of the ArcGIS API for JavaScript, 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 of the ArcGIS API for JavaScript, 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), then 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 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.     

        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.     

One common issue is that the path to the proxy file is entered into the application incorrectly. You can use Firebug or another browser debugging tool to determine if the proxy is located. Open Firebug and activate the NET tab. Then run your application and watch the requests and look for the request that POSTs to the proxy. In the image below the request is red and a 404 error is returned which means that the proxy page cannot be found. If you hover your mouse over the request in the NET tab you'll see the location where the application is looking for the proxy.