Tokens and token services
A token is used when ArcGIS Server security is configured to the ArcGIS Managed Authentication option. A token represents the identity of a user to an ArcGIS Web service. A token is issued to a client application by a token service, which is a Web service. A client application must provide a valid token to a secured ArcGIS Web service to access it.
ArcGIS Managed Authentication based on tokens
The following sequence of events takes place whenever a client application tries to access a secured ArcGIS Web service:
- The client makes a request to a secured ArcGIS Web service.
- The ArcGIS Web service responds that a token is required and provides the URL of the token service.
- The client requests a token from the token service by supplying a valid user name and password.
- The token service validates the user name and password and, if they are valid, returns a token to the client.
- The client makes a request to the secured ArcGIS Web service and includes the token along with the request.
- The ArcGIS service validates the token, 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 ArcGIS Web services, the client software must be able to obtain and use the token, as in the process outlined above. ESRI client applications, such as ArcGIS Desktop, automatically handle the process of acquiring tokens from the token service and presenting tokens to the secured ArcGIS Web service. The behavior of ArcGIS clients when connecting to a GIS Web service that requires token-based authentication is described below.
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.
In Web applications, the end user of the application does not enter credentials to access the ArcGIS service in the browser. The credentials to access the ArcGIS Web service are specified when building the Web application in ArcGIS Server Manager or the Eclipse/NetBeans IDE. This credential is 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. The Web application-level security can be configured using ArcGIS Server Manager. Using custom programming, it is possible to pass through credentials from the end user to the ArcGIS Web service. See the ArcGIS Server Developer Help for more information.
Configuring a token service
A token service is a Web service that is installed as part of ArcGIS Server. It communicates with the principal and security stores that maintain user and role information to authenticate incoming requests for tokens. Once the user credentials are authenticated, a token is issued and can be used to consume a secured ArcGIS Web service.
Before you start a token service on your ArcGIS Server instance, you need to configure it. You configure a token service by navigating to the Settings page on the Security panel in Manager and clicking the Security for GIS Services tab. Choose the option ArcGIS Token Service Authentication and click Configure to configure and start a token service on your ArcGIS Server instance.
For more information on token timeout values and shared keys, see "Timeout of tokens" and "Shared key for the token service" below.
Secure connection (HTTPS/SSL) required for the 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, using either 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 may be disabled so that tokens may be obtained using nonsecure HTTP. Be aware that passwords sent using HTTP can 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 navigating to the Settings page on the Security panel and clicking Configure on the Security for GIS Services tab. To maintain 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, a short expiration time would mean that applications need to recycle tokens more frequently, thereby adding overhead.
The token service installed with ArcGIS Server requires that you supply two expiration times during its configuration:
Short expiration time (default expiration time)
The token service issues a token with a short expiration time when the client does not specify a timeout value or provide a client identifier when requesting a token.
ArcGIS Desktop clients and Web ADF applications use tokens with short expiration times while consuming secured ArcGIS Web services.
Long expiration time (maximum expiration time)
This is the maximum expiration time that 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. When providing a client ID, a client can request a token with an expiration time between one minute and the long expiration time (maximum expiration time). A request for a token with an expiration time longer than the maximum will result in an error.
JavaScript developers wanting to consume secured services can request a token with a specific expiration time by using the GetToken Web page.
For more information on how to request tokens, see "Requesting tokens" below.
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 is sent to the client. When the client sends a request for an ArcGIS Web 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 ArcGIS Web 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, navigate to the Settings page on the Security panel and click Configure on the Security for GIS Services tab. In the Configure Local Token Service dialog box that appears, set the value for the property Shared key for encrypting token. 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 may be used, including nonalphanumeric characters. The key should be set to a value that could not easily be guessed by anyone who might intercept a token. Since users will not need to use or remember the key, complexity does not pose the same issues as it does 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 AES, 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 requests for tokens. This is typically only required when building Web applications with the ArcGIS Server API for JavaScript 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 instance at https://<webserver>:<port>/arcgis/tokens/gettoken.html (or if you have exported the token service and deployed it on a Web server, substitute <webserver> with the Web server domain name and replace arcgis/tokens with the context path to the deployed application).
To use the GetToken page, enter the following information:
- User name and password: User credentials that are valid for the ArcGIS Web services on ArcGIS Server. The user name and password are case sensitive. The valid users are those configured using ArcGIS Server Manager on the Settings panel.
- Client ID: An identifier for a 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 API for JavaScript. The client ID may be specified in one of two ways:
- IP address: This ties the token to the machine specified. Use this option if the token will always be used on the machine specified, such as on a Web application built with the ArcGIS Server API for SOAP, in which the server will make requests to the ArcGIS Web service. This approach can also be used when testing and troubleshooting issues with ArcGIS Server.
- HTTP referrer: This is the URL of the page from which the request is made to the ArcGIS Web service. Use this approach if building an application with the ArcGIS Server API for JavaScript or other REST-based applications, where individual clients will request maps and data directly from the ArcGIS Web service.
- Expiration: The expiration for a token between one minute and the maximum.
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.
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 |