Understanding the ArcGIS Server Proxy Page and CORS

by | May 15, 2015

One thing that appears to cause more confusion than anything else among beginner users of the ArcGIS Server API for JavaScript is the use of the proxy page and CORS. Let’s see if we can clear up that confusion once and for all.

Before we get into the actual mechanics of working with the proxy page and CORS, let’s briefly outline what problem they are trying to solve.

Subscribe to our weekly email

In web development, if you build an application on your web server at http://www.mywebserver.com and then try and request a resource residing on another server (such as a map service running on ArcGIS Online) then the default behavior is to disallow the request. Why? Because it is considered a security risk. This “same origin policy” is there to prevent a malicious script on one page from obtaining access to sensitive data on another web page. Which is all well and good as a general principle, but really gets in the way of things when we’re building web mapping applications which routinely pull in all sorts of different services residing on different hosts. There have been a number of different workarounds for this, but the ones that interest us most as ArcGIS Server API for JavaScript developers are CORS and the proxy page. CORS stands for Cross Origin Resource Sharing. It is an extension to the standard HTTP protocol that allows servers to use new headers in their requests (Origin, and Access-Control-Allow-Origin) which explicitly allow access to resources on other servers that would otherwise have been forbidden by the same origin policy. In order for your web application to use CORS, two things have to happen:

    1. Your browser must support it. Many modern browsers do, but you can check yours at http://caniuse.com/#feat=cors
    2. The server that hosts the resource that you want must also support CORS. ArcGIS Server 10.1 and above supports CORS out of the box, but there are still many servers out there (including some of Esri’s own servers) that don’t.

Assuming both these things are in place, then you are good to go. If you cannot rely on CORS, then you need to install and configure a proxy page on your web server. Instead of sending the request for the remote resource directly to the web server that hosts it, your application sends the request to the proxy page on your server first, and the proxy then forwards the request to the remote server. It then relays the response returned by the remote server directly back to your application. Because the connection is made to your server, and the data from the resource your requested comes back from your server, the browser does not complain about your web application and the resource that you are interacting with being on different hosts. It’s really that simple! So now you know how the proxy works, and all you need to do is pick the right one for your web server, configure it, and tell your application where it is. Thankfully, Esri’s documentation on that is really good. Hopefully the time will come when everything supports CORS, but until then you need to make provision for those browsers and ArcGIS servers that don’t by using the proxy page.


Recent Posts

Mark Lewin
Mark is an authorized Esri and CompTIA CTT+ certified instructor, Esri certified Web Developer Associate and experienced web development professional. In a career spanning over 15 years, Mark has built dozens of sophisticated web applications and taught others to do the same, and has a particular interest in web mapping. Highlights include the development of a highly complex volcanic ash cloud modeling system for the UK's Met Office and using ArcGIS Server and the Flex API, and a state of the art cell phone tracking system for a defense contractor using the ArcGIS Server API for JavaScript. He has taught hundreds of GIS professionals how to build custom applications using Esri's ArcGIS Server and open source platforms (MapServer, OpenLayers, Leaflet) and delivered geospatial software tutorials and demonstrations to thousands

Sign up for our weekly newsletter
to receive content like this in your email box.