Proxy pages with the API

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.

If CORS is not enabled on a web server a proxy is needed to bypass security on these resources.

All requests via esriRequest assume CORS support. Regardless of the type of data you are accessing (e.g. ArcGIS Enterprise services, WMS and WMTS services, etc.), the web server being accessed needs to support CORS. If this is not the case, or you are unsure as to whether CORS is supported, a proxy should be configured within the application. This proxy can be referenced within the application via the proxyUrl. By adding this, the application has a fallback mechanism in place in case the service request fails due to lack of CORS support.

Steps to working with the proxy

1 - Get or build a third-party proxy

A proxy is installed and runs on its own web server, not on an Esri server or on the computer where ArcGIS Enterprise is installed, (unless your web server also hosts the ArcGIS Enterprise instance).

2 - Use the proxy

In order for your application 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.

1
2
3
require(["esri/config"], function(esriConfig) {
  esriConfig.request.proxyUrl = "/proxy/Java/proxy.jsp";
});

It is also possible to configure your application with specific proxy rules. These rules instruct the proxy to use 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().

1
2
3
4
5
6
require(["esri/core/urlUtils"], function(urlUtils) {
  urlUtils.addProxyRule({
    urlPrefix: "my-standalone-arcgis-server.com",
    proxyUrl: "/proxy/Java/proxy.php"
  });
});

3 - Testing and deploying 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. In other words, all HTTP/HTTPS requests should return with a valid response and no requests should fail. 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. 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.

• If possible, enable logging for the proxy. Once enabled, messages are written to the log that may be useful when troubleshooting the issue.

• Make sure you have specified the correct location for your proxy in your application code. This is the most common cause of errors. 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 in the application this means that the proxy was not found. Inspect the request properties to view the path where the application is looking for the proxy.

4 - Securing the proxy application

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.

Additional Information

• Access secure resources
• CORS