dot
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 will provide authentication information to connect to a secure service.

Keep in mind that 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 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, you must obtain a token and use it in your application. You can generate a token before an application is deployed or generate a token programatically at runtime. You have three basic choices for utilizing services secured with token-based authentication:

  1. Create a token and apply it to the appropriate Silverlight/WPF components (e.g. layer, task) that use the token secured services. This solution involves a design-time change to the Silverlight/WPF application.

  2. At runtime, prompt the user to provide authentication credentials and generate a token for them. Provide a dialog in the Silverlight application or use the browser to handle a challenge response from a secure service. The browser will provide a standard authentication dialog to enter a username 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 will store a long term token -or- store authentication credentials to generate a token at runtime. The user credentials and token will remain secure in the server-side proxy page and thus not be visible to the client.

Obtaining a token

You can create a token using the token service Web page or generate a token programatically. 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. Programatic solutions usually generate short term tokens at runtime and 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. Visit 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:

    1. The User Name and Password provided to you by the ArcGIS Server system administrator. For ArcGIS Online Premium Services, use your ESRI Global Account.

    2. 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.

      At the moment, the Referer 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 will cause an ArcGIS Server service to refuse requests.

  5. Click the "Generate" button. A token should appear at the bottom of the page. Copy this value and use it in your application. If no token appears or if an error message displays, ensure that the values you entered are correct.

To generate a token programatically, construct a Web request. Here's 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 username 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 (e.g. 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 two ways:

HTTP/Windows authentication

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

There are two approaches to accessing a secured service using HTTP/Windows authentication:

  1. Prompt the user to provide authentication credentials. Provide a dialog in the Silverlight application or use the browser to handle a challenge response from a secure service. The browser will provide a standard authentication dialog to enter a username and password. If using HTTP Basic authnication all communication with a service should be handled 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 will store credentials to authenticate with the secure service, relay requests to the service, and return responses to the client. The user credentials will remain secure in the server-side proxy page and thus not be visible by the client.

Tips

If you are the administrator of an ArcGIS Server site, you can restrict access to your ArcGIS Web services. Information on restricting access is available in the ArcGIS Server Help system.