Tokens and Token Service

Release 9.3 E-mail This Topic Printable Version Give Us Feedback

What is a token?

A token represents the identity of a user to the ArcGIS Server (when using ArcGIS Authentication for GIS Services). A token is issued by a Token Service (a web service). A user (or an application) who wants to consume a GIS web service published by the GIS Server that has been secured by ArcGIS Managed Authentication has to provide a valid token.

ArcGIS Managed Authentication based on Tokens

When tokens are required for a GIS service (when using ArcGIS Token based Authentication), client software uses the GIS service by this approach:

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

Consuming Secured GIS Services using Tokens

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 handle obtaining and using tokens. When connecting to an ArcGIS Server Internet service that requires a login, client behavior is as follows.

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.

Configuring a Token Service

A Token Service is a web service that is installed as a part of the ArcGIS Server 9.3. It communicates with a Principal Store (also called Security Store) that maintains user and role information to authenticate incoming requests for tokens. Once the user credentials are authenticated, a token is issued to be used to consume a secured GIS service (secured using ArcGIS Managed Authentication).

Before you start a token service on your ArcGIS Server instance, you need to configure it. You configure a token service by going to the 'Security for GIS Services' tab on Security > Settings page and enabling security (click the checkbox), selecting ArcGIS Managed Authentication and clicking the 'Configure' button for starting a token service on your ArcGIS Server instance.

For more information on token timeout values and shared keys, please see the 'Timeout for Token Service' and 'Shared key for Token Service' sections on the document.

Secure Connection (HTTPS/SSL) required for Token Service

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

For internal testing purposes only, the requirement for HTTPS may be disabled, so that tokens may be obtained using non-secure HTTP. Be aware that passwords sent using HTTP may be intercepted by anyone connected to the network.

Timeout of tokens

When the Token Service is enabled, you can set the timeout of the token in Manager, by going to Security > Settings in the 'Security for GIS Services' tab. For maintaining the security of the token, each token is associated with an expiration time. The end user may see a timeout or other error message if an expired token is used.

Tokens with shorter expiration times are more secure as a compromised token can only be used within a smaller time window. However, short expiration time would mean that applications need to recycle them more frequently adding overhead.

The Token Service installed with the ArcGIS Server at 9.3 requires that you supply 2 expiration times during its configuration.

Shared Key for Token Service

The shared key for the Token Service is used to encrypt the token. The token is encrypted with the username and other information and is 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. To set the shared key, go to Security-Settings in Manager, and under the Security for GIS Services tab, click the Configure button (when you have chosen ArcGIS Token based Authentication). In the Settings dialog that appears, set the Shared key value. The key should be set to sixteen (16) characters (any characters beyond 16 are not used). It is recommended to use a set of random characters for the key. Any characters may be used, including non-alphanumeric characters. The key should be set to a value that could not 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 encryption method known as Advanced Encryption Standard (AES), 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.

Requesting Tokens

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 Server 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 ArcGIS Server at https://<webserver>/arcgis/tokens/gettoken.html (or if you have exported the token service and deployed it on a web server, substitute the <webserver> with the web server domain name and replace the 'arcgis/tokens' with the deployed context).

To use the GetToken page, enter the following information:



Request URL

The token request to the Token Service can also made over a URL. 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: