Skip To Content

About ArcGIS tokens

ArcGIS Server provides a proprietary token-based authentication mechanism where users can authenticate themselves by providing a token instead of a user name and password. An ArcGIS token is a string of encrypted information that contains the user's name, the token expiration time, and some proprietary information. To obtain a token, a user provides a valid user name and password. ArcGIS Server verifies the supplied credentials and issues a token. The user presents this token whenever accessing a secured resource.

Token properties

Life-span of a token

To maintain the security of the token, each token is associated with an expiration time. The end user may see a time-out or other error message if an expired token is used.

Tokens with shorter expiration times are more secure, as a token intercepted by a malicious user can only be used within a smaller time window. However, a short expiration time means that applications need to request new tokens more frequently.

Two parameters define the life-span of issued tokens:

  • Lifespan of Short-lived Tokens: When a client requests a token but does not specify a time-out value, a short-lived token is issued. The issued token is only valid for the duration defined by this property. When a client requests a token with a time-out value less than the short-lived token life-span setting, a token with the requested expiration value is issued.
  • Lifespan of Long-lived Tokens: When a client requests a token with a time-out value, the requested time-out value is compared with the duration defined by this property. If the requested time-out value is less than the long-lived token life-span, a token with the requested expiration value is issued. If the requested time-out value exceeds the long-lived token life-span setting, a token is still issued but with an expiration that matches this property.

Defining the shared key

An ArcGIS token is a string of encrypted information. The shared key is the cryptographic key used to generate this encrypted string. The more complex the shared key, the harder it is for a malicious user to break the encryption and decipher the shared key. If a user is able to decipher the shared key, replicate the ArcGIS Server encryption algorithm, and obtain the list of authorized users, the user will be able to generate tokens and consume any secured resource on that particular ArcGIS Server.

Before defining a shared key, consider the following:

  • The shared key should be set to 16 characters (any characters beyond 16 are not used). It is recommended that you use a sequence of random characters for the key. Any characters may be used, including nonalphanumeric characters.
  • The key should not be set to a dictionary word or a common value that is easily guessed. Since there is no need to remember the key or use it elsewhere, key complexity does not pose the same issues as it does with passwords.
  • The token is encrypted with the shared key using the 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.
  • In highly secure environments, it is recommended that you change the shared key on a periodic basis. Keep in mind that if you change the shared key, you may need to update your applications to use the new shared key. All existing embedded tokens will become invalid once you change the shared key.

Secure transmission of tokens

To prevent the interception and misuse of tokens, the use of a secure connection using HTTPS is recommended. The use of HTTPS ensures that the user name and password sent from the client and the token returned from ArcGIS Server cannot be intercepted.

When building custom ArcGIS client applications that use GET requests to access web services secured using ArcGIS token-based authentication, it is recommended that the token be sent in the X-Esri-Authorization header instead of a query parameter. This prevents intermediaries on the network, such as proxies, gateways or load-balancers from being able to obtain the token. The example HTTP GET request below sends the token in the X-Esri-Authorization header:

GET https://arcgis.mydomain.com/arcgis/rest/services/SampleWorldCities/MapServer?f=pjson HTTP/1.1
    Host: arcgis.mydomain.com
    X-Esri-Authorization: Bearer xMTuPSYpAbj85TVfbZcVU7td8bMBlDKuSVkM3FAx7zO1MYD0zDam1VR3Cm-ZbFo-

If ArcGIS Server uses ArcGIS Server authentication and not Web-tier authentication (IWA, HTTP BASIC, PKI, etc) the standard HTTP Authorization header may be used instead of the X-Esri-Authorization header:

GET https://arcgis.mydomain.com/arcgis/rest/services/SampleWorldCities/MapServer?f=pjson HTTP/1.1
    Host: arcgis.mydomain.com
    Authorization: Bearer xMTuPSYpAbj85TVfbZcVU7td8bMBlDKuSVkM3FAx7zO1MYD0zDam1VR3Cm-ZbFo-