Configuring the Token Service

The Token Service is a new service available with ArcGIS Server 9.3. The token service enables users to be authenticated in order to use secured GIS Web services. Tokens provide security for services by ensuring that only users who provide appropriate credentials can access secured services. The token is a string of encrypted information sent between client and server. The token contains the user's name, expiration time and other information.

Tokens provide a level of security for your Web GIS services, but are not as secure as certain other methods, such as Integrated Windows authentication. The security of your system with tokens depends on controlling access to the tokens. Requests for tokens require a secure connection (https) by default, but you may also want to require https for all requests that use the token. This would mean requiring https for the folder that contains the secured GIS services. You can require https for a services folder by opening the properties of the folder in Manager or in ArcCatalog and checking the box to "Require Encrypted Web Access".

The Token Service is a Web service that is installed with the ArcGIS Web applications component during the installation of ArcGIS Server. At the current version of the software, the Token Service is automatically enabled when needed. The Token Service is enabled when you specify that users will be stored in either Microsoft SQL Server or a custom membership provider (see Overview of setting up users and roles). The Token Service is not enabled or utilized when you specify that Windows user accounts are used to authenticate users of your GIS services, unless you use SQL Server or a custom provider for roles, and you enable tokens for user authentication.

When the Token Service is enabled, you can set the maximum allowable time-out for tokens. This setting is described in Time-out of tokens. You can also set the encryption key to a unique value for your installation; see Shared key for Token Service. These are the only configuration steps available for the Token Service at the current version.

When tokens are required for a GIS service, client software uses the GIS service by this approach:

1. The client makes a request to the GIS service.
2. The GIS server responds that a token is required and provides the URL of the Token Service.
3. The client requests a token from the Token Service by supplying a valid user name and password.
4. The Token Service validates the user name and password with the database (or custom membership provider) and, if valid, returns a token to the client.
5. The client makes a request to a GIS service and includes the token along with the request.
6. The GIS server validates the token and sends the response for the service request back to the client.

What if you want to allow users to access services without having to supply a token or login? You can allow anonymous access to services or folders by using the Everyone role (see Setting permissions for a service or folder).

When the Token Service is enabled and required for accessing GIS services, the client software must be able to obtain and use the token, as in the process outlined above. As of 9.3, ESRI clients have been updated to automatically obtain and use tokens. When connecting to an ArcGIS Server Internet service that requires a login, the client behavior is as follows:

• ArcGIS Desktop (ArcMap, ArcCatalog): The user enters a valid user name and password into the connection dialog box. If the correct user name and password are entered, the user can use a secured service normally. If no user name or password is entered or the login is incorrect, the connect may be made, but no services will be available unless the service allows the Everyone or Anonymous role. The exception is when the server uses Windows authentication to identify users, and no username or password are entered into the connection dialog box. In this case, ArcGIS Desktop sends the identity of the user who started ArcCatalog as the identity to the server. If the user is in a role permitted for the server, then the connection will succeed and permitted services will display.
• ArcGIS Explorer: Same behavior as with ArcGIS Desktop.
• Web Application Developer Framework (ADF) applications (both Java and Microsoft .NET Framework): The Web application uses the credentials previously entered into Manager or in the developer environment. In Manager, the user name and password are entered when adding the GIS server during creation of a Web application. In a developer environment, such as Microsoft Visual Studio, the user name and password are entered when adding the GIS resource to the application.
• JavaScript applications (ArcGIS JavaScript API, ArcGIS JavaScript Extension for the Google Maps API, ArcGIS JavaScript Extension for Virtual Earth, and other REST-based applications): The client must be capable of providing a token when one is required to access the service. In most cases, it will not be appropriate to embed the user name and password for the service into the client-side JavaScript. Instead, a long-lived token can be obtained from the Token server and may be included in the client-side page. The token is then included in the request for the service. For details on acquiring the token, see the section GetToken Web page in this topic. For information on requesting a resource with a token, see the appropriate API resource.
• SOAP-based applications: Applications that use a SOAP toolkit to access the Web service description language (WSDL) of the GIS Web service without using the ADF connection classes need to acquire and use tokens explicitly. See the Developer Help for information and examples.

Note that in Web applications, the end user of the application in the browser does not enter credentials for the GIS service. The login information for the service must be specified in advance in Manager or in the development environment. The same credentials are used for all users of the Web application. The Web application itself may be secured to require a login, but this login is validated separately, based on the configuration of security for the Web application in Manager or other means. Using custom programming, it is possible to pass through credentials from the end user to the GIS service. See the Developer Help for more information.

Manager allows you to set several parameters for the Token Service: expiration window for tokens (both short lived and long lived) and the shared key for encryption. Each of these settings is explained below.

Time-out of tokens

When the Token Service is enabled, you can set the time-out of the token in Manager, through Security-Settings. The time-out determines the time period that the token will be valid. The end user might see a time-out or other error message if an expired token is used.

Shorter token time-outs provide better security but may cause legitimate users to encounter time-outs during their use of services if the application does not detect it and obtain a new token (Desktop and ADF clients are able to obtain new tokens). Tokens are given a time-out setting to limit their unauthorized use. If a hacker manages to monitor the communication between the authorized user and the server, the token could be captured by the hacker. If the token is intercepted, the time-out will limit its period of use. For increased security, therefore, you may wish to set the time-out of tokens to a shorter period. The disadvantage of a short token timeout is that if the application does not renew the token, the user be unable to continue with their session once the token times out, and may need to restart their application or connection with the server.

If you are writing a custom application, you may want to detect token time-out and supply an appropriate message or obtain a new token. See the Developer Help for more information.

Two token expiration windows are defined on the Security-Settings page:

• Short-lived tokens: This time-out setting applies to clients requesting a token without a client ID, or with a client ID but without an expiration time. The time-out value set here is always applied for short-lived tokens. This timeout setting is used with ArcGIS Desktop and Web ADF applications.
• Long-lived tokens: This timeout setting is typically used with JavaScript applications. The long-lived token setting in Manager is typically much longer than for short-lived tokens. The time-out setting is a maximum allowable value: the client can request a token for any period up to the maximum setting in Manager.
  
  In order to obtain a long-lived token, the client must include a client ID and expiration time. The client ID is either the client IP address, or the Web Referrer URL, which is the URL of the web application that the client browser is using. The request must also include the timeout for the token. If no timeout is specified, the timeout specified for short-lived tokens is used.

A good way to prevent the capture and unauthorized use of tokens is to require the use of HTTPS (SSL) for all communication with GIS services. To do this, you would require secure communication (SSL) for the ArcGIS/Services Web application. For instructions on requiring HTTPS (SSL) for an application in IIS, see Setting up SSL.

Shared key for the Token Service

The shared key for the Token Service is used to encrypt the token. The token is encrypted with the user name and other information and sent to the client. When the client sends a request for a GIS service, it includes the token. The server then uses the shared key to decrypt the token. The server verifies the identity of the client before permitting access to the GIS service. The shared key ensures that the server has created the token.

Since the shared key is critical to ensuring the identity and authorization of the client, the key must be set to a unique value of proper length. Manager will set the shared key to a random value when the token service is enabled. You can set the key yourself if desired. To set the shared key, go to Security-Settings in Manager, and under the Token Service heading, click the Settings button. On the Settings dialog box that appears, set the Shared key value. The key should be set to 16 characters (any characters beyond 16 are not used). It is recommended that you use a set of random characters for the key. Any characters can be used, including nonalphanumeric characters. The key should be set to a value that cannot easily be guessed by anyone who might intercept the token. Since users will not need to use or remember the key, complexity is not an issue as might be true with passwords.

The token is encrypted with the key using the Advanced Encryption Standard (AES) encryption method, also known as Rijndael. The 16 characters in the key represent the 128 bits used for encryption. For more information on encryption and the AES standard, consult security references or someone in your organization with expertise in security and cryptography.

GetToken Web page

An HTML page is provided with the Token Service to enable manual requesting of tokens. This is typically only required when building Web applications with the ArcGIS JavaScript API or for testing and troubleshooting. Clients such as Web ADF applications and ArcGIS Desktop automatically retrieve tokens and do not require this page. The GetToken page is located on the Web server at https://<webserver>/ArcGIS/Tokens/gettoken.html (or if you installed at a nondefault instance name, substitute the name for ArcGIS).

To use the GetToken page, enter the following information:

• User name and password that are valid for the GIS Web services on the GIS server. The valid users are those previously set in ArcGIS Server Manager under Security-Settings.
• Client ID, which identifies the machine making the request to the Web service. The client ID is required to obtain a long-term token that is valid for an extended period, as is typically required when using the ArcGIS JavaScript API. The client ID ensures that if the token is captured during transmission, it cannot easily be used by a third party to issue requests to the GIS server (note that spoofing with either option below is possible). The client ID can be specified in one of two ways:
  • IP address: This ties the token to the machine specified. Use the IP address if the token will always be used on the machine specified, such as on a Web application built with the ArcGIS Server SOAP API, where the server will make requests to the GIS Web service. This approach can also be used when testing and troubleshooting issues with the GIS server.
  • HTTP Referer: This is the URL of the page from which the request is made to the GIS Web service. Use this approach if building an application with the ArcGIS JavaScript API or other REST-based application where individual clients request maps and data directly from the GIS Web service.
• Expiration,which sets the time the token will expire based on the time issued. If the client attempts to send a request after the token expires, a token-expired code will be returned. ESRI clients (Desktop, ArcGIS Explorer and Web ADFs) know how to obtain a new token. Other clients may need to restart the application. The specified expiration time is used only if the Client ID is set. If the Client ID is omitted, the expiration time will use the short-lived token time set in Manager. If the Client ID is included but the expiration time exceeds the maximum time configured for long-lived tokens in Manager, then the time configured in Manager for long-lived tokens is used instead.

If you are concerned about possible misuse of the GetToken page, you can remove it or limit access to it using IIS Manager or file system permissions. Note that even if the GetToken page is not available, token requests can still be made to the token service with the gettoken request to the folder, using the request format as described in the next section.

Token request format

The token request to the server is made with a URL (GET) request. The clients that work with tokens, such as ArcGIS Desktop and the Web ADF, use this approach, as does the GetToken page described in the previous section. The query string of the URL contains the user login and other information. For example, the following URL might be used to get a token from a server:

https://myserver.example.com/arcgis/tokens?request=gettoken&username=myuser&password=secret1&clientid=ref.http://myserver.example.com&expiration=1440

This request would get a token for user myuser for a web application running at the same server (myserver.example.com), with a validity period of one day (1440 minutes).

The following parameters may be specified in the query string:

• request: The value of this parameter is always gettoken (request=gettoken). Required.
• username: The user name for a user on the system. Required.
• password: The password for the user on the system. Required.
• clientid: An identifier for the client. Use a "." character between type and value. Type may be either (a) ip, where an IP address of the client is specified, or (b) ref, where an HTTP Referrer is specified. Use ref when requesting a token for a JavaScript API application. Optional, but if not specified, then the token will use the short-lived token timeout setting.
• expiration: The time the token will be valid from the time issued. Value is in minutes. Optional. If not included, expiration will use the short-lived token timeout setting. If expiration is included and the clientid is included, the value may be up to the long-lived token timeout setting (if an expiration beyond the long-lived token timeout is requested, the token will expire using the long-lived token expiration setting). If expiration is included but clientid is not included, the token will expire using the short-lived token timeout, and the expiration parameter will be ignored.

Secure connection (HTTPS/SSL) required for Token Service

A secure connection using HTTPS (Secure Sockets Layer or SSL) is required by default when requesting a token from the Token Service. HTTPS encrypts the user name and password during transmission. The client must use HTTPS when requesting a token, either by the standard method where the user name and password are included in the query string (used by ArcGIS Desktop, the Web ADF controls, and other clients), or the GetToken.html Web page.

For internal testing purposes only, the requirement for HTTPS can be disabled, so that tokens can be obtained using nonsecure HTTP. Be aware that passwords sent using HTTP can be intercepted by anyone connected to the network. Using HTTP for tokens should only be necessary on a development server where your organization's policies prohibit the installation of the IIS Web server on the development machine. In these circumstances, development is typically done using the file-based Web server in Visual Studio ("Cassini"), which does not support the use of SSL/HTTPS. When IIS is available, SSL should always be used to protect against the capture and unauthorized use of user names and passwords. For information on setting up SSL, see Setting up SSL.

To set the Token Service to allow nonsecure HTTP requests for tokens, follow these steps:

1. Open the file <Web server root>\ArcGIS\Tokens\web.config with a text or XML editor (if your ArcGIS instance is not in the default location, C:\Inetpub\wwwroot\ArcGIS, then go to the location of your ArcGIS instance).
2. Locate the following tags inside the <appSettings> section. If the tag(s) do not exist, add them.

   
   <appSettings>
        <add key="RequireSSL" value="True" />
        <add key="TokenServiceURL" value="https://myserver/ArcGIS/tokens/" />
        ...
   </appSettings>
   
   

3. Set the value of the RequireSSL key to False, and change the value of the TokenServiceURL from https to http. Then save the file. No restart of IIS should be needed, as any change in the web.config file should restart the Token Service application.
4. Repeat the above steps for the web.config files in <Web server root>\ArcGIS\rest and <Web server root>\ArcGIS\Services.

Remember to restore the SSL requirement when appropriate. To re-enable the requirement for SSL in the Token Service, restore the RequireSSL setting to True, set the TokenServiceURL to use https, then save the file. Do this for each web.config file in the Tokens, rest, and Services folders.