Using the proxy page

This page describes an older version, please read about the latest version at:
https://developers.arcgis.com/en/flex/guide/

Version 2.5

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 want to use the proxy page in your application in either or both of the following two situations:

NoteNote:

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 handle these situations, your application can have client browsers send service requests to the proxy page running on your web server. Your proxy page then sends the requests to the ArcGIS Server service. Since the proxy requires extra time and resources on your server, you should use the proxy page only when your application requires it.

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. Secure the web application, especially when using a service with token-based authentication
  4. Test to ensure the proxy is working correctly

Step three is critical for applications that use tokens. If you do not secure the application correctly, the ArcGIS Server services used by the application are vulnerable to unlimited use by unauthorized persons. See the following section on securing the application for further information.

Here are some technical details on the proxy page for interested readers. In the first situation described earlier, with lengthy URLs, the proxy page allows the browser to perform a POST request rather than the GET request that the browser would normally do with service requests. A POST request does not have the same relatively low limit on the amount of data sent as does a GET request. However, for security reasons, browsers are not allowed to POST except back to the server that sent the page to the browser. Hence, the proxy page must run on the same web server where your application runs. In the second situation, the authentication token is configured in the proxy page, rather than in the HTML page downloaded by the client. The browser sends a request (by either GET or POST) to the proxy page. The proxy page appends the token to the request and forwards the request to the ArcGIS Server computer, then returns the response to the browser. This way, the end user does not have access to the token. This can provide enhanced security for the ArcGIS Server service, provided that the security measures described later in this topic are implemented.

Downloading and configuring the proxy page

You must download the proxy page and include it in your web application. The proxy page runs on your local web server, not on an Esri server or on the ArcGIS Server computer (unless your web server also hosts the ArcGIS Server instance). Three proxy pages are available, each running on a specific server-side platform: ASP.NET, Java/JSP, and PHP. Your web server must support one of these server-side platforms to use the proxy page. Download the appropriate page for your platform.

Unzip and save the proxy page to your web application's folder, then configure your application or server so that it runs the proxy page.

Configure the proxy page for the token.

For ASP.NET

  1. If you will be using the proxy page for services with token-based authentication, obtain a token for the service. For instructions, see Working with secure ArcGIS services. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.
  2. Open the configuration proxy page (proxy.config for ASP.NET) in a text or XML editor.
  3. For each ArcGIS Server that uses the proxy page, add a <serverUrl> entry to the configuration XML file within the <serverUrls> section. See the proxy configuration file for examples. The serverUrl element can have the following attributes:

    • url—The URL of the ArcGIS Server machine or the service. If multiple services in the same server are used in the application, the url can point to the services root. If only a single service on the server is used, the url can be set to the full service URL.
    • matchAll—Whether to use the token for all requests with this URL stem. If this attribute is true and the url attribute is set to the services root, the entry can be used for multiple services in the application.
    • token—The authentication token obtained in Step 1. Optional—used only for services secured with token-based authentication.

    If multiple services on the same server are used in the application, the URL may point to the service root (for example, http://www.example.com/arcgis/rest/services), and the matchAll parameter set to true. See commented examples included in the downloaded file. Multiple server entries may be added if more than one ArcGIS Server computer is used in the application.
  4. Save the configuration file.

Examples

  • The service is at http://www.example.com/arcgis/rest/services/MyMapService/MapServer, and the proxy is used because of lengthy requests sent in queries, then the element may be set to: <serverUrl url="http://www.example.com/arcgis/rest/services/MyMapService/MapServer" matchAll="false" ></serverUrl>.
  • Two services are used on the same server: http://www.example.com/arcgis/rest/services/MyMapService/MapServer and http://www.example.com/arcgis/rest/services/MyGPService/GPServer. Neither service requires a token and the proxy is used because of lengthy requests. The serverUrl element would be: <serverUrl url="http://www.example.com/arcgis/rest/services" matchAll="true" ></serverUrl> Alternatively, two serverUrl elements may be added, one for each service, as in the first example.
  • The service is a secured service at https://www.example.com/arcgis/rest/services/MyMapSecureService/MapServer. A token is obtained from the server's token service and added to the entry. <serverUrl url="https://www.example.com/arcgis/rest/services/MyMapSecureService/MapServer" matchAll="false" token="5fFo4%2fI4Tv8IGSqSYbpUNORRD%2fYxXMSPo6NEHNNGMpt9CMknpXIjEVqYGm3uuQnU" ></serverUrl>.

The mustMatch attribute in the containing <ProxyConfig> element controls whether only specified sites may be proxied. This attribute should generally be set to true. If set to false, the proxy page forwards any request to any server. This could potentially allow your proxy page to be used to send requests to third-party servers without your permission.

For Java/JSP

  1. If you are using the proxy page for services with token-based authentication, obtain a token for the service. For instructions, see Working with secure ArcGIS services. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.
  2. Open the configuration proxy page (proxy.jsp) in your favorite text editor.
  3. The JavaServer Pages (JSP) code defines a serverUrls variable. This represents the servers for which you want this JSP to act as a proxy. It is a String array where each String has the "<url>,<token>" syntax. The token is optional. Add URLs to the services you want to access over here. See commented examples included in the JSP. Multiple server entries may be added if more than one ArcGIS Server computer is used in the application.
    NoteNote:

    While this sample proxy includes the configuration in the JSP, you may want to configure the URLs in a separate resource file and have your application reference that file.

  4. Save the JSP.

For PHP

  1. If you are using the proxy page for services with token-based authentication, obtain a token for the service. For instructions, see Working with secure ArcGIS services. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.
  2. Open the proxy page (proxy.php) in your favorite text editor.
  3. Using the "mustMatch" variable, specify whether the proxy should forward requests only to specified servers. If this value is true, the proxy only forwards requests to the servers specified in the "serverUrls" variable (see Step 4). If this value is false, the proxy forwards requests to any server.
    CautionCaution:

    Be aware that this could potentially allow your proxy page to be used to send requests to third-party servers without your permission.

  4. Using the "serverUrls" variable, specify the servers that this proxy forwards requests to if "mustMatch" is true. It is an array where each element configures an ArcGIS server or service using an array with keys named "url", "matchAll" and "token". The sematics of these keys are similar to the correspondingly named attributes used in the ASP.NET proxy.
  5. Save the PHP file.

All users—For services with token-based authentication, the URL of the service should use HTTPS, for example, https://www.example.com/arcgis/rest/services/MyMapService/MapServer. This ensures that the token appended to the query string of the request is encrypted and cannot be intercepted and used by unauthorized parties. This is especially important when the communication between your web server and the ArcGIS Server service travels over the Internet, and not just on the local network.

Adding code to use the proxy page

For your application's page to send requests through the proxy, you must add code to the page as follows. In the startup function (for example, OnPageLoad) in the JavaScript code of your page, add a line to set the proxy page. The following example is for the ASP.NET version; substitute proxy.jsp or proxy.php as appropriate. 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).

<esri:ArcGISDynamicMapServiceLayer
     id="treasureMap"
    url="http://www.example.com/ArcGIS/rest/services/TreasureMap/MapServer"
    proxyURL="proxy.ashx"/>
<!-- or with an absolute URL -->
<esri:ArcGISDynamicMapServiceLayer
    id="treasureMap"
    url="http://www.example.com/ArcGIS/rest/services/TreasureMap/MapServer"
    proxyURL="http://myserver/proxy.ashx"/>

or with ActionScript:

treasureMap.proxyURL = "proxy.ashx"
// or with an absolute URL
treasureMap.proxyURL = "http://myserver/proxy.ashx"

Securing the web application

This step is essential if the application uses services with token-based security, and the proxy page is configured with the token. If you do not secure the web application, anyone can send any request through your proxy page to the ArcGIS Server service, without using your application page. Your proxy page could be used for unauthorized disclosure of data from the service, or for inappropriate or high volume use of the service.

To secure the web application, you need to do both of the following:

  1. Require users of the application to login (authenticate) to use the application. This ensures that only authorized users can use the application, including the proxy page. How you require authentication depends on the type of server software you are using. For IIS/ASP.NET servers, you may use Windows authentication or ASP.NET forms. For more information and instructions, see the Security Model topic on Microsoft's web site. For other platforms, consult the documentation on implementing authentication for your platform.
  2. Require use of HTTPS via Secure Sockets Layer (SSL). At a minimum, the login page should be secured, especially if using forms or Basic authentication. For maximum security, you may require HTTPS for all communication in the application. Note, that to require HTTPS for an application, you must obtain and install an SSL certificate for your web server. If using IIS, the Configuring SSL on a Web Server or Web Site (IIS 6.) topic on Microsoft's web site describes how to obtain and install SSL certificates.

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 an IIS/ASP.NET environment, you can open the application in Visual Studio or Visual Web Developer Express, open the proxy.ashx page, and set a breakpoint in the ProcessRequest method, then run the application with Debug-Start. 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.

12/2/2011