Using the proxy page

Version 3.7

About the proxy page

The proxy page consists of server-side code that runs on your web server. The browser sends the request to your proxy and your proxy in turn, forwards the request to the ArcGIS Server service.

You may need to use a proxy in the following situations:

  • The service you are trying to connect to is on a different domain than your application, and the service does not have a crossdomain file allowing your Flash application access.
  • The application uses a service that is secured with token-based authentication, and you do not want 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 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.

For a JavaScript application, a proxy page is also required when the requests exceed the limit on the length of the uniform resource locators (URLs) imposed by the browser. This does not apply to Flex API applications as the Adobe Flash Player can "POST" requests when needed.

To use the proxy page, you need to perform the following steps, which are described in detail as follows:

  1. Download and configure the proxy page appropriate for your server
  2. Add code to your application page to enable use of the proxy
  3. Test to ensure the proxy is working correctly
  4. Secure the proxy application

Downloading and configuring the proxy page

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 system requirements. Make sure you follow these instructions in order to setup and configure the proxy on your web server.

Adding code to use the proxy page

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 your proxy page is not in the same directory as the web application, adjust the path appropriately. The path should use a relative URL (for example, ../proxy.ashx), or a URL relative to the root (for example, /Proxy/proxy.ashx).

    proxyURL="URL to proxy"/>

or with ActionScript:

treasureMap.proxyURL = "URL to proxy"
// or with an absolute URL
treasureMap.proxyURL = "http://<URL to proxy>"

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 ProcessRequest method 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 may also set breakpoints in your Flex application, or insert trace() or 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 can be 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 this means that the proxy was not found. Inspect the request properties to view the path where the application is looking for the proxy.

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