The ArcGIS JavaScript Extension for Virtual Earth 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 one or more of these situations:

To handle these situations, your application can have client browsers send service requests to the proxy page (an http handler) 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 see an example of a page that uses the proxy, view the "Querying data using a buffer" sample in the "Perform a Query" category of the Interactive SDK. This sample uses the proxy because the buffer created around the user click, although it appears to be a circle, consists of a polygon with many individual points. In order to send this polygon to the server as part of the QueryTask, the proxy must be used.

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 originating the request. Hence the proxy page must run on your local Web server. 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.

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.

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 item can have these attributes:
    • url: the URL of the ArcGIS Server REST services (for example, http://www.example.com/arcgis/rest/services), or the URL of the service (for example, http://www.example.com/arcgis/rest/services/MyGISService). 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 forward requests with this URL stem. If this attribute is true and the url attribute is set to the services root, then the entry may be used for multiple services in the application. If false, the request's service URL must match exactly.
    • token: the authentication token obtained in step 1. Optional - used only for services secured with token-based authentication.
    See examples below and also in the downloaded proxy page file. Multiple server entries may be added if more than one ArcGIS Server computer is used in the application.
  4. Save the configuration file.
  5. Only if the proxy page will be connecting to services secured with HTTP or Integrated Windows Authentication: the identity of the process running the page must be set. If the service security uses Integrated Windows Authentication in IIS, you can assign the proxy page to an application pool in IIS that uses a fixed Windows identity. Otherwise, you will need to add code to the proxy page to set the identity with each request. You can do this by setting the credentials property of the WebRequest in the proxy page. For an example, see the online topic Using secured Web services and tokens in the SOAP API section of the Developer Help or, if you have an installation of ArcGIS Server, in the corresponding page in your local Developer Help.

Examples

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 the URLs of the services that the proxy page will work with. 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 file.

For both ASP.NET and Java , if you are using 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 may use a relative URL (e.g., ../proxy.ashx), or a URL relative to the root (e.g., /Proxy/proxy.ashx). For JSP with the proxy page at the server root, a full URL may be appropriate, but it must use the same server and port as the applications that will use the proxy page (e.g., http://samedomain:sameport/proxy/proxy.jsp).

ESRI.ArcGIS.VE.Config.Proxy = "proxy.ashx"; // use proxy.jsp or proxy.php as appropriate

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 ESRI.ArcGIS.VE.Config.Proxy property must also be set.

ESRI.ArcGIS.VE.Config.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 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 ESRI.ArcGIS.VE.Config.Proxy property value and start over.