Secure services

ArcGIS Server web services can be secured to permit only authorized users by using one of two authentication methods: token-based or HTTP (including Windows) authentication. The ArcGIS Server system administrator provides authentication information to connect to a secure service.

Keep in mind, Silverlight application source code and communication between the Silverlight application and a remote server, even over HTTPS, can be viewed by the client. This means a client can discover authentication credentials and tokens defined in the source code or included in request content.

Token-based authentication

Services that use token-based authentication require that a token be included in each request for a map, query, address match, geoprocessing job, and so on. A token is an encrypted string derived from information about the authorized user, date and time, and client making the request.

To use a service that requires tokens, obtain a token and use it in your application. You can generate a token before an application is deployed or generate a token programmatically at runtime. You have the following three basic choices for utilizing services secured with token-based authentication:

1. Create a token and apply it to the appropriate Silverlight components (for example, layer, task) that use the token secured services. This solution involves a design-time change to the Silverlight application.
2. At runtime, prompt the user to provide authentication credentials and generate a token for them. Provide a dialog box in the Silverlight application or use the browser to handle a challenge response from a secure service. The browser provides a standard authentication dialog box to enter a user name and password. All communication with a token service should be handled over a secure connection (HTTPS).
3. Use a proxy page to provide access to a secure service by defining the ProxyURL property on a service layer. The proxy page stores a long term token or store authentication credentials to generate a token at runtime. The user credentials and token remain secure in the server-side proxy page and thus, not visible to the client. Download an example proxy page.

Obtaining 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 Referrer 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 the ArcGIS Server site administrator or the ArcGIS 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 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:
   1. The user name and password. For ArcGIS Server content, these are the credentials provided to you by the ArcGIS Server system administrator. For content on ArcGIS.com, use your ArcGIS.com account user name and password.
   2. An identifier to define a distinct ID for the web application that uses the token. You have two options: Web application URL/HTTP Referrer or IP address. At the moment, the Referrer header cannot be set by a Silverlight application. If you need to create a long term token, use the IP option with a proxy page.
   3. 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 application.
   Tip:

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

To generate a token programmatically, construct a web request. The following is an example using C# and the .NET Framework:

string tokenService = 
    "http://hostname/ArcGIS/tokens?request=getToken&username=test&password=my.password&expiration=30";
System.Net.WebRequest request = System.Net.WebRequest.Create(tokenService);
System.Net.WebResponse response = request.GetResponse(); 
System.IO.Stream responseStream = response.GetResponseStream(); 
System.IO.StreamReader readStream = new System.IO.StreamReader(responseStream); 
theToken = readStream.ReadToEnd();

Note:

If generating a token in Silverlight, the user name and password will be visible on the client, even over an HTTPS connection. In most cases, you'll want to store credentials in a server-side resource (for example, proxy page) and direct requests for token secured services through the server resource.

Using the token in your application

Once you have a valid token, use it in your application in one of the following two ways:

• Set the token property manually on a layer, such as a map service layer, or on a task. To set the token property at design-time, generate the token manually (for example, use the token service web page). Unfortunately, the Referrer header cannot be set by a Silverlight application, which is required for long term tokens. As a result, only short term tokens can be used, which renders this solution untenable for most applications:

  <esri:ArcGISTiledMapServiceLayer
      Token="cggEFLivAeuzeEzxqYbt3XVXwJHtBINpCLQdq4YaxmOghNgsnB6iLWjlHsd7xomB"
      Url="http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer"/>
  

• Use it in requests brokered by a proxy page. Keep in mind, the proxy page option offers a high level of protection for the token, as end users do not have access to it. Download the proxy page and review the README file for more information.

HTTP/Windows authentication

When a request is made to a service secured with HTTP authentication (including Windows authentication using Internet Information Services [IIS]), the server issues an authentication challenge. The application or user must respond with appropriate user credentials using standard HTTP authentication methods.

The following shows the two approaches to accessing a secured service using HTTP/Windows authentication:

1. Prompt the user to provide authentication credentials. Provide a dialog box in the Silverlight application or use the browser to handle a challenge response from a secure service. The browser provides a standard authentication dialog box to enter a user name and password. If using HTTP Basic authentication, handle all communication with a service over a secure connection (HTTPS).
2. Use a proxy page to provide access to a secure service by defining the ProxyURL property on a service layer. The proxy page stores credentials to authenticate with the secure service, relays requests to the service, and returns responses to the client. The user credentials remain secure in the server-side proxy page and thus, not visible to the client.

Tips

• If services in the Silverlight application are secured using HTTP Basic authentication, require that users employ HTTPS when accessing the application to prevent password interception. Other authentication methods, such as Digest or Integrated Windows Authentication (IWA), may protect user logins, but for maximum security, HTTPS is recommended when users are logging in.
• Supplying end users with a user name and password is not appropriate when multiple services requiring different credentials are in an application.
• Authentication is only required for the initial request to a secure service. This may result in a user encountering a login dialog box midway through a session. For example, if the user requests a non-secure map, then tries to perform a query on a secure service, the login dialog box appears only after the query. To avoid this, send a request in the background to the query service when the application starts, such as a simple REST request for service information. The user will be prompted to log in upon startup, rather than in the midst of the application session.

If you are the administrator of an ArcGIS Server site, you can restrict access to your ArcGIS web services. For additional information, see How ArcGIS Server security works.