Proxy pages

Before CORS, it was necessary to work with a proxy page. This was helpful as it was used to bypass the issue many applications had when accessing resources that were not on the same origin.

Even though enabling and using CORS is the preferred method, it should also be noted that proxies are still required if:

the web server/browser are not enabled for CORS or do not support JSONP format
needing anoymous access to secured services within an application.

This topic specifically discusses working with proxies, additional information on working with CORS can be found in the CORS guide topic.

The following use cases discuss when it is appropriate to use a proxy.

Example: Server is not enabled for CORS and the resource response is not in JSONP format

There may be instances where CORS is not enabled on the server and JSONP is not supported. In this case, a proxy is needed to bypass security on these resources.

For example, all requests to WMS services initially go through a GetCapabilities request. This initial response loads a XML file. If the server is not enabled for CORS, a proxy is required since the response is not in JSONP format.

/proxy.php?https://oceanwatch.pfeg.noaa.gov/thredds/wms/satellite/PP/bfp1/8day?SERVICE=WMS&REQUEST=GetCapabilities

Example: Server is not enabled for CORS although services support JSONP

If using a GET request, there is no need for a proxy, (see the CORS guide topic). Whereas using a POST request requires the need for a proxy. Generally, this is seen in instances where:

The application performs editing.
The response returned from the request is very large, i.e. approximately 2000+ characters. This was once common in applications that performed intensive geometry functions, (e.g. buffering). This is not so common anymore as much of this is now handled on the client.

Example: Services are behind a firewall

There may be instances where there are security settings that prevent cross domain access. In these cases, the proxy page should be used all the time. This can be set using esriConfig.request's forceProxy property.

Example: Building an application that targets end users not known to the ArcGIS platform

There may be scenarios where you need to create an application to allow anonymous access to features requiring credentials to the ArcGIS platform. Some premium features include routing, batch geocoding, and analysis. In this situation, the application logs in to the platform using the credentials stored in the proxy. Please see ArcGIS Security and Authentication for details.

The following steps details how to get started working with the proxy.

Get the proxy

The proxy runs on your local web server, not on an Esri server or on the computer where ArcGIS Server is installed (unless your web server also hosts the ArcGIS Server instance). Three proxies are available for download, each targeting a specific server-side platform:

Download the appropriate proxy for your platform. Each proxy download includes installation instructions and information on any system requirements make sure you follow these instructions in order to setup and configure the proxy on your web server.

Use the proxy

In order for your appliction to route requests through the proxy, you must add code to your application defining the location of where the proxy is hosted.

If all requests in your application use the same proxy, specify the location using the request object's proxyUrl property. You can also specify if requests should always go through the proxy using the request object's forceProxy property. This forces the application to use the proxy for all AJAX requests made using request and any images added via the <img> element.

require(["esri/config"], function(esriConfig) {
  esriConfig.request.proxyUrl = "/resource-proxy/Java/proxy.jsp";
  esriConfig.request.forceProxy = true;
});

It is also possible to configure your application with specific proxy rules. These rules define the proxy for specific resources that have an identical URL prefix. When the application tries to access a resource via this URL, the request is sent through the specified proxy. The request's proxyRules property is an object listing all these proxy rules. To populate this, use the urlUtils.addProxyRule().

require(["esri/core/urlUtils"], function(urlUtils) {
  urlUtils.addProxyRule({
    urlPrefix: "route.arcgis.com",
    proxyUrl: "/resource-proxy/Java/proxy.php"
  });
});

Testing and deploying the application

Once you have configured the proxy page wqith 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 a breakpoint in the proxy page and detect whether it is operating correctly. For example in IIS/ASP.NET environment, you can open the application in Visual Studio and set a break point in the ProcessRequest method in the proxy.ashx., then run the application in debug mode. The execution should halt at the breakpoint, and you should be able to detect where the problem is. You can also set break points in the JavaScript functions of your application, or insert console statements to display values during execution.
Each proxy has an associated config file. Set this file's, mustMatch attribute to false to proxy all requests. If the application works now, you may not have listed the service in the serverUrls section or you may have a typo in the serverUrl. Don't forget to set this attribute back to true when you have finished troubleshooting the proxy.
Enable logging for the proxy. Once enabled, messages are written to the log that may be useful when troubleshooting the issue.
Make sure you've specified the correct location for your proxy in your application code. You can use browser developer tools to determine if the proxy is successfully located. To do this, activate your browser debugging tools then examine the network requests. Look specifically for requests that POST to the proxy. If you see a 404 error this means that the proxy was not found. Inspect the request properties to view the path where the application is looking for the proxy.

Securing the proxy application

If the application uses services with token-based security, and the proxy is configured with the username and password or client_id and client_secret the proxy application needs to be secured so that only authorized applications have access. Please refer to ArcGIS Security and Authentication documentation for additional details.