ArcGIS API for JavaScript ^3.29

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:

• The resource you are trying to access is on a different domain than your application and Cross Origin Resource Sharing (CORS) support is not available. CORS is a specification that allows a web server to interact with a web browser to determine if a cross-origin request should be allowed.

  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.

• The application accesses a service that is secured with token-based authentication and you do not wish to allow users to view the token, or you do not want to transmit the token over the network between your Web server and your users.
• You are building an application that targets end users are not known to the ArcGIS platform. In this situation the application will login to the platform using information stored in the proxy. View Authentication, OAuth 2.0, and ArcGIS for details.
• Requests exceed the limit on the length of the uniform resource locators (URLs) imposed by the browser. Common scenarios where you may run into URL length issues are when you use the buffer from a complex polygon as the input to a query task or if you specify a spatial reference using well-known text (WKT).

  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.

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 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.

Using the proxy

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.

Test 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:

• If your application environment supports debugging mode, you may be able to set breakpoint in the proxy 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 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.

• Set the ProxyConfig mustMatch attribute to false to proxy all requests. If the application works when this value is set to false then you may not have listed your 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 located. To do this activate your browser debugging tools then examine the network reqeusts and look 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.

Secure 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. View Authentication, OAuth 2.0, and ArcGIS for additional details.