Configuring the Token Service

The Token Service authenticates users when ASP.NET Authentication is used (in other words, when SQL Server or a custom provider is used for the user and role stores). A token acts as a key for accessing a secure service and is only given to authenticated users. The token is a string of encrypted information that contains the user's name, expiration time and other information. The token is given to the authenticated user through the Web services available at <ArcGIS Server Instance>/Tokens.

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.

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. ESRI clients automatically obtain and use tokens. When connecting to a GIS Web service that requires a login, the client behavior is as follows:

• ArcGIS Desktop (ArcMap, ArcCatalog), ArcGIS Explorer, and Web ADF applications: The user enters a valid user name and password into the connection dialog box for accessing the service in the desktop application or developer environment. The application takes care of communicating with the Token Service and acquiring a valid token. The user or developer does not need to interact with the Token Service directly.

  Note:

  In ArcGIS Desktop, you cannot connect to a WMS or WCS server using credentials managed by the Token Service. If your WMS or WCS server is secured, you'll need to enter the account credentials managed by the server's user and role store. For information on connecting to WMS and WCS servers in Desktop, see Connecting to GIS servers.

• REST-based applications (JavaScript, Flex, Silverlight/WPF, SharePoint): Because these applications run in a browser and can therefore be viewed by anyone who has access to them, it would not be appropriate to embed the user name and password for the service into the application. Instead, a token can be obtained from the Token Service. The token is then included in the URL request for the service (for example, http://url.to.service?token=<token String>). 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 ArcGIS Server SOAP SDK for information and examples.

Note that when using a token 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. When using IIS authentication (users stored in Windows) credentials are automatically passed through from the application to the underlying Web services.

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 time-out is that the developer will need to embed a new token in the application before the token times out.

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 time-out setting is used with ArcGIS Desktop and Web ADF applications.
• Long-lived tokens: This time-out setting is typically used with the REST-based (JavaScript, Flex, Silverlight/WPF, and SharePoint) 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. 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 time-out for the token. If no time-out is specified, the time-out 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 it might be 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 user name and password are case sensitive. 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 REST-based APIs. 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 Referrer: This is the URL of the page from which the request is made to the GIS Web service without the HTTP(s) prefix. Use this approach if building an application with the ArcGIS JavaScript API or other REST-based API where individual clients request maps and data directly from the GIS Web service. For example, if your application were to be hosted at http://www.esri.com you would use www.esri.com as your referrer. If you might be accessing this application from multiple subdomains like gis.esri.com, then you could use just the portion of the URL that would be common to both URLs. In this example, the referrer would be esri.com. Be careful not to make the referrer shorter than it needs to be, as this will weaken the security of the token.
• 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

To get a token from the server, you make a URL request. The clients that work with tokens, such as ArcGIS Desktop, Web ADF, Web API, and mobile clients use this approach, as does the GetToken page described in the previous section.

Requesting a token using the tokens endpoint

You can request a token using the tokens endpoint. 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.myserver.example.com&expiration=1440&f=json&callback=myfunction

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.

  Note:

  HTTPS/SSL encrypts the username and password during token transmission. For more information, see the Secure connection (HTTPS/SSL) section below.

• clientid: Optional parameter that identifies the client. Use a "." character between type and value. If clientid is not specified, the token will use a short-lived token timeout setting.

  Values:

  • ip: IP address of the client.

    Example: clientid=ip.10.14.102.85

  • ref: The base URL of the webapp where this token will be used. This parameter must be specified if the value of the client parameter is referrer.

    Example: clientid=ref.http://myserver/mywebapp

  • requestip: If the value is specified as requestip (request IP), the token is generated for the IP from where the request originated.

    Example: clientid=requestip

• expiration: Optional parameter specifying how long the token will be valid from the time issued. The value is in minutes. If this parameter is not included, expiration will use the short-lived token time-out setting.

• f: New at ArcGIS Server 10.0 Service Pack 1 (SP1), this optional parameter specifies the output format. It accepts the value "json" to return the result in a json format. If this parameter is not specified, the token will be generated in a text format.

  Example: {"token":"hjSXkAQl2uczsyE9T3NDvhcso6WVYWSAqBcn1GFB-L8.","expires":"1289513369381"}

  The expiration time is represented in milliseconds since January 1, 1970.

• callback: Optional parameter specifying the name of the callback function. When callback is included the output is always returned in a json format.

Requesting a token using the generateToken endpoint

New at ArcGIS Server 10.0 Service Pack 1 (SP1), you can also request a token using the generateToken endpoint . For example, the following URL might be used to get a token from a server:

https://myserver.example.com/arcgis/tokens/generateToken?username=myuser&password=mypass&client=referer|ip|requestip&referer=referer&ip=ipaddress&expiration=expiration&f=json&callback=myfunction

The following parameters may be specified in the query string:

• username: The user name for which the token is generated. Required.

• password: The password for the username. Required.

  Note:

  HTTPS/SSL encrypts the username and password during token transmission. For more information, see the Secure connection (HTTPS/SSL) section below.

• client: Optional parameter that identifies the client. If clientid is not specified, the token will use a short-lived token timeout setting.

  Values:

  • referer: The base URL of the webapp where this token will be used. This parameter must be specified if the value of the client parameter is referrer.

    Example: referer=http://myserver/mywebapp

  • ip: The IP address of the machine that from which the token will be used. This parameter must be specified if the value of the client parameter is ip.

    Example: ip=10.14.102.85

  • requestip: If the value is specified as requestip (request IP), the token is generated for the IP from where the request originated.

• expiration: Optional parameter specifying how long the token will be valid from the time issued. The value is in minutes. The expiration cannot be longer than the maximum allowed time for a long-lived token.

  Example: expiration=60

  Note:

  If client and expiration parameters are not included, a short lived token will be generated and expiration will use the short-lived token time-out setting.

• f: Optional parameter specifying the output format. It accepts the value "json" to return the result in a json format. If this parameter is not specified, the token will be generated in a text format.

  Example: {"token":"hjSXkAQl2uczsyE9T3NDvhcso6WVYWSAqBcn1GFB-L8.","expires":"1289513369381"}

  The expiration time is represented in milliseconds since January 1, 1970.

• callback: Optional parameter specifying the name of the callback function. When the callback parameter is included, the output is always returned in a json format.

Special characters in token requests

The following characters are not supported in token requests: +, /, ?, %, #, and &. If you use one of these characters in a query string to request a token, the request will fail. If you need to use one of these characters, you must substitute the appropriate escape sequence from the table below:

Character	Character substitute
+	%2B
/	%2F
?	%3F
%	%25
#	%23
&	%26

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 through 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="XYZ" />
   <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 reenable 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.

Making the Token Service accessible from the Internet

As discussed above, ArcGIS Desktop, ArcGIS Explorer and Web ADF clients need access to the Token Service in order to request a token for secure services. When making an ArcGIS Server instance accessible on the Internet, you will need to change the URLs for accessing the Token Service so it can be found on the Internet.

When ArcGIS Server is installed, it stores the name of the machine in the URL for accessing the Tokens Service. In an intranet setting where that machine name can be resolved, this will work fine. However when you make that machine accessible over the Internet, the machine name will not be able to be resolved by your clients.

To fix this, you must change three web.config files in the rest, Services, and Tokens folder of your ArcGIS Server instance (<Web Root>\<ArcGIS Server Instance name>). Open each of these web.config files in a text editor and follow these steps:

1. Within the appSettings element find the element with the key: TokenServiceURL.
2. Change the value for this key from https://<machine name>/ArcGIS/tokens to https://<public domain name>/ArcGIS/tokens.