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 programmatically 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 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 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 ArcGIS 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 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 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 programmatically, construct a Web request. Here's an example using C# and the .NET Framework: a

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:

• Set the token property manually on a layer, such as a map service layer, or a task. To set the token property at design-time, you need to generate the token manually (e.g. 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 see the read me for more information.

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 authentication 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 services in the Silverlight application are secured using HTTP Basic authentication you should require that users employ HTTPS when accessing the application to prevent password interception. Other authentication methods, such as Digest or Integrated Windows Authentication, 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 present 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 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 will appear 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. Information on restricting access is available in the ArcGIS Server Help system.