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:

1. The client makes a request to a secured ArcGIS Web service.
2. The ArcGIS Web service 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 and, if they are valid, returns a token to the client.
5. The client makes a request to the secured ArcGIS Web service and includes the token along with the request.
6. 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 an ArcGIS Server Internet service that requires token-based authentication is described below.

• ArcGIS Desktop (ArcMap, ArcCatalog): The user enters a valid user name and password into the connection dialog box. If no user name or password is entered, or if the login is incorrect, the software prompts the user to enter correct credentials. Once a correct user name 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 the 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 API for JavaScript, ArcGIS Extension for the Google Maps API, ArcGIS Extension for Bing Maps, 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 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 this token can 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 GetToken Web page. For information on requesting a resource with a token, see the appropriate API help.

• 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 ArcGIS Server Developer Help 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 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.

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.

  メモ:

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

• 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.

  メモ:

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

• 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

  メモ:

  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.