Tokens and Token Service

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.

ArcGIS Desktop (ArcMap, ArcCatalog): The user enters valid username and password into the connection dialog. If no username or password is entered, or the login is incorrect, the software will prompt the user to enter correct credentials. Once correct username and password are entered, the user can use the service normally.

ArcGIS Explorer: Same behavior as with ArcGIS Desktop.

Web 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 username 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 username and password are entered when adding the GIS resource to the application.

JavaScript applications (ArcGIS JavaScript API, ArcGIS JavaScript Extension for Google Maps, ArcGIS JavaScript Extension for Virtual Earth, and other REST-based applications): The client must be capable of providing a token to access the service that requires a token. In most cases, it will not be appropriate to embed the username and password for the service into the client-side JavaScript. Instead, a long-lived token can be obtained from the Token server, and this token 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" below. 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 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.

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.

Short Expiration Time (Default Expiration Time)

The Token Service will issue a token with a short expiration time when the client does not specify a timeout value or when the client does not provide a client identifier when requesting a token.

ArcGIS Desktop clients and Web ADF applications use tokens with short expiration time while consuming secured services.

For more information on how to request tokens, please see the 'Requesting Tokens' section in this document.

Long Expiration Time (Maximum Expiration Time)

This is the maximum expiration time for a token which the Token Service can issue. All token requests that specify an expiration time for the tokens when making the request must provide a client ID. While providing a client ID a client can request for a token with an expiration time between 1 minute and Long Expiration Time (maximum expiration time). A request for a token with expiration time longer than the maximum will result in an error.

JavaScript developers wanting to consume secured services can request for a token with a specific expiration time by using the 'GetToken' web page.

For more information on how to request tokens, please see the 'Requesting Tokens' section in this document.

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:

User name and password: User credentials 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: An identifier for a machine making the request to the Web service. The client ID is required in order to obtain a long-term token that is valid for an extended period, as is typically required when using the ArcGIS Server JavaScript API. The client ID may be specified in one of two ways:

IP address: this ties the token to the machine specified. Use 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 may 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 Server JavaScript API or other REST-based application, where individual clients will request maps and data directly from the GIS Web service.

Expiration: the expiration for a token between 1 minute and the maximum.

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:

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 associated with the username. 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 expiration time setting. If expiration is included and the clientid is included, the value may be up to the long expiration time 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.