Proxy pages
This topic specifically discusses working with proxies, additional information on working with CORS can be found in the CORS guide topic.
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
- building an application that requires anonymous access to secured services
The following use cases discuss when it is appropriate to use a proxy.
Example: Server is not enabled for CORS
There may be instances where CORS is not enabled on the server. If this is the case, 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 Server services, WMS and WMTS services, etc.), the 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.
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.
Steps to working with the proxy
1 - 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.
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.
require(["esri/config"], function(esriConfig) {
esriConfig.request.proxyUrl = "/resource-proxy/Java/proxy.jsp";
});
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"
});
});
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. 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
ProcessRequestmethod 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
configfile. Set this file's,mustMatchattribute to false to proxy all requests. If the application works now, you may not have listed the service in theserverUrlssection 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 have 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
POSTto 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.
4 - 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.