The proxy consists of server-side code that runs on your web server. Your browser based web application sends the request to the proxy and the proxy then forwards the request to the remote web server and relays the response returned by the remote server back to your application.
You may need to use a proxy in the following situations:
Note: In order to use CORS both the browser and the target web server must support CORS. ArcGIS Server 10.1 supports CORS out of the box. For earlier versions, an administrator can add CORS support. Visit enable-cors.org for detailed instructions.
Note: 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.
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 each targeting a specific server-side platform: ASP.NET, Java/JSP, and PHP. Download the appropriate proxy for your platform from GitHub. 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.
In order for your application to route requests through the proxy you must add code to your application to define the location of the proxy. If all requests in your application will use the same proxy you can specify the proxy location using proxyUrl
. You can also specify whether or not the proxy should always be used for communication using alwaysUseProxy
esriConfig.defaults.io.proxyUrl = "<url_to_proxy>" esriConfig.defaults.io.alwaysUseProxy = false;
In the code above, esriConfig
refers to the object returned by the esri/config module.
Another option is to setup a proxy rule that defines the proxy for a set of resources with the same URL prefix. If the request URL matches a rule, then the request will be routed through the proxy. To define a proxy rule specify the url for the proxy and the prefix for the resources that need to be accessed through the proxy.
urlUtils.addProxyRule({ urlPrefix: "route.arcgis.com", proxyUrl: "<url_to_proxy>" });
In the code above, urlUtils
refers to the object returned by the esri/urlUtils module.
Note: If you are storing login information (username and password or client_id and client_secret) in the proxy you will want to use the addProxyRule
option so that requests to the resources with the specified URL prefix are routed through the proxy.
Once you have configured the proxy with the application, test the application to ensure that requests are processed correctly. The application should function as it did before the proxy was implemented. If not, you may need to troubleshoot the proxy. The following troubleshooting tips may help you find and fix the problem:
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 will halt at the break point, and you may be able to detect where the problem lies. You can also set break points in the JavaScript functions of your application, or insert alert() statements to display values during execution.
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. View Authentication, OAuth 2.0, and ArcGIS for additional details.