Setting up a Proxy

04-07-2015 02:54 AM
Labels (1)
by Anonymous User
Not applicable
4 1 15.5K
A proxy page stands between a server and an application. By using a proxy, you allow an application to authenticate on your behalf, bypassing a challenge and accessing secured services inside of an application. While the token is hidden, an application can access secured services with token-based authentication; a proxy handles massive post requests over 2,048 characters. Additionally, you can use a proxy when a resource and an application are on separate domains, as well as when cross-origin resource sharing (CORS) support is unavailable.

Today, we'll walk through the steps of downloading, setting up, and hosting a proxy page on an IIS7 server. For a programming language, we use Esri's JavaScript API. In addition to setting up the proxy page, we will add a proxy rule to the Directions widget sample.

To download the Directions widget sample, click here.

Our journey begins at the glorious GitHub site.

Note: The proxy page must be located on the same server as your JavaScript application.
  1. Navigate to to obtain the most recent release of the proxy.
  2. Click 'Source code(zip)' to download the .zip file to your local drive.

    Download a proxy from GitHub.

  3. Extract the files to your server (in this case, IIS Server), and navigate to the resource proxy folder, 'C:\\inetpub\wwwroot\resource-proxy-master', where you extracted the files. There are three sub-folders inside, each containing a proxy for the respective server type:
  • DotNet - Internet Information Services (IIS) server
  • Java - Apache Tomcat server
  • PHP - Apache server
                              Folders under resource-proxy-master
To view additional information within each folder located in the, open the file with Notepad++ or a preferred integrated development environment (IDE).
  1. Depending on the server, copy one of the three folders. In this example, we use an IIS server. Copy the DotNet folder, and place it in your wwwroot folder.
  2. Click Start. In the ‘search for programs and files’ box, type IIS, and open the IIS Manager.
  3. Expand the server name, the Sites folder, and Default Web Site.

    Internet Information Services (IIS) Manager

  4. Right-click the DotNet folder in the directory, and select Convert to Application.

    Convert proxy to an application

  5. Ensure the application pool is 4.0 or greater. In this example, we use ASP.NET v4.0. Ensure the folder icon is a globe.addApp.png
  6. In Windows Explorer, open the DotNet folder, and right-click proxy.config. Open the file in Notepad++ or a preferred IDE.
  7. Inside the proxy.config file, you see the following in XML format:

    proxy configuration file

    We recommend keeping the global mustMatch="true". When this is true, all requests made to the proxy can only go through specified serverUrls.

    For testing purposes, you can change the global mustMatch="false"; this allows any proxy requests to pass through.
  8. Since the direction's sample uses and, we add two <serverUrl> tags.

Note: When using ArcGIS Online services the recommended workflow is to use a client id and client secret. The client id and client secret are obtained from If secured services from ArcGIS for Server used, then we would input a username and password. For this example, we use services from ArcGIS Online serverUrls.

Input client id and secret inside the proxy.

  1. The following steps demonstrate how to configure the proxy in your JavaScript application. There are a couple of ways to configure the proxy inside of a JavaScript application. For this particular example, we use the proxy rule.
  • In the JavaScript application, add two proxy rules:
    esri.addProxyRule({urlPrefix: "", proxyUrl:"http://<yourServer>/<pathToProxy>/proxy.ashx" });

    esri.addProxyRule({   urlPrefix: "", proxyUrl: "http:// <yourServer>/<pathToProxy>/proxy.ashx" });
  • As another possibility, add the "esri/urlUtils" module in the require statement, and add the following rule:                                                                                                           urlUtils.addProxyRule(urlPrefix: "", proxyUrl: "http://<yourServer>/<pathToProxy>/proxy.ashx" });urlUtils.addProxyRule({urlPrefix: "", proxyUrl: "http://<yourServer>/<pathToProxy>/proxy.ashx"});  
  • Here is another way to configure the proxy. = "<url_to_proxy>" = false; The proxyUrl is the path to your proxy page hosted on IIS.
  1. Run the hosted application, and open the Developer tools.
  2. Type in an origin and destination. Our journey ends with step by step directions accompanied by a map visual. 

    Get Directions

Happy travels!
Marla K. and Akshay H. - SDK Support Analysts
1 Comment
New Contributor III

In point 12 above, you've shown three ways to add proxy rules to the JavaScript application.  I've downloaded an AGO Web AppBuilder application (not the dev version), and can't figure out where to put this code.  Suggestions?

arcgis online webapp builder‌ wab