Configuring a proxy

With the ArcGIS Viewer for Silverlight, you can use a proxy page to store user credentials for accessing secure services. A 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 which then provides access to the secure service. The proxy page stores a long term token or stores authentication credentials to generate a token at runtime. The user credentials and token remain secure in the server-side proxy page and thus, are not visible to the client. For additional information, see the Secure Services topic in the ArcGIS API for Silverlight.

The ArcGIS Viewer for Silverlight provides an example proxy page that you can use to handle communication with the ArcGIS Server services used in your application. Typically, you will need one proxy page per application if you are using tokens because tokens are application specific.

See the following sections in this topic for more information:

• Download and install the proxy page
• Obtain a token
• Configure the proxy page

Download and install the proxy page

The following steps describe how to download and install the proxy page on your web server. 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).

Note:

If you will be using the proxy page for services with token-based authentication, obtain a token for the service. If your application uses multiple ArcGIS Server systems that require tokens, obtain a token for each server.

Before proceeding, ensure that you have ASP.NET 2.0 or higher installed and registered with IIS. If ASP.NET is not configured with IIS, follow the instructions for the version of IIS you are running in the ASP.NET and IIS Configuration help topic on MSDN.

1. Download the example proxy page, then unzip and save the contents to a folder on your web server's root directory. In IIS, the default location for the web server's root folder is c:\inetpub\wwwroot. If you plan on using the proxy for multiple sites, you can create a folder in the web root directory called proxy and place the contents there.
2. Open IIS Manager. This Microsoft Knowledge Base article provides instructions for opening IIS Manager depending on the version of IIS you are using.
3. Create a Web Application for the proxy folder; these steps differ depending on the version of IIS you are using.
   • For IIS 5 or 6, use the following steps:
   1. In the Default Web Site, right-click the proxy directory and click Properties.
   2. On the Directory tab in the Application Settings section, click the Create button and click OK:
   • For IIS 7, use the following steps. For more information, see Create a Website (IIS 7).
   1. In the Default Web Site, right-click the Proxy directory and click Add Application:
   2. Specify the Alias and Physical Path in the Add Application dialog box, and click OK:

Obtain a token

You can create a token using the token service web page or generate a token programmatically. The token service web page is used to generate a long-term token when you know the client id via a Referer or IP address. Programmatic solutions usually generate short-term tokens at runtime which reduces the chance of a compromised token. To create a token using the token service web page, do the following:

1. Get the URL of the service. The URL can be obtained from either the ArcGIS Server site administrator or the Services Directory.
2. Go to the URL. You are routed to the Services Directory and may be prompted to log in.
3. Click Get Token in the upper right corner of the page that displays the service information. If there is no Get Token link, the service is either not secured or it uses HTTP/Windows authentication.
4. The ArcGIS token service web page appears. Note the use of HTTPS in the URL. The token service is normally accessed over a secure connection to ensure that transmission of user data is encrypted. Enter the following information on the page:
   • The User Name and Password provided to you by the ArcGIS Server system administrator.
   • An Identifier to define a distinct ID for the web application that will use the token. You have two options: Web application URL/HTTP Referer or IP address. Use the URL to the Viewer.xap file in the deployed application (for example, http://<hostname>/Apps/MyApplication/Viewer.xap) instead of just http://<hostname>. If you need to create a long term token, use the IP option with a proxy page.
   • Expiration time. Define the amount of time the token will be valid. Shorter expiration periods are safer in the event that the token is intercepted by unauthorized users, but you must obtain a new token and apply it before the old one expires. Expired tokens cause an ArcGIS Server service to refuse requests.

5. Click Generate. A token appears at the bottom of the page. Copy this value and use it in your proxy page (see the following section).
   Tip:

   If no token appears or if an error message displays, ensure that the values you entered are correct.

Configure the proxy page

1. Open the configuration proxy page (proxy.config) in a text or XML editor.
2. For each ArcGIS Server that will use 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—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—Specifies 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—Authentication token. Optional—used only for services secured with token-based authentication.

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

   The mustMatch attribute in the containing element controls whether only specified sites can be proxied. This attribute should generally be set to true. If set to false, the proxy page will forward 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.

3. Save the configuration file. Note the URL of your proxy page, as you will need it when adding a secured map service to ArcGIS Viewer for Silverlight.