FRAMES | NO FRAMES

 

B U S I N E S S   A N A L Y S T   S E R V E R   10.5   S E C U R I T Y

Using Secured Business Analyst Server Web Services

Business Analyst Server Web services may be secured to permit only authorized users. Business Analyst Server implements security in REST by using the token-based authentication.

Token-Based Authentication

This method is typically used when users are stored in a database or file, rather than as operating system users. To authenticate the request, you must obtain a token from the token service recognized by ArcGIS Server instance. If you have access to the user name and password in your server-side code, you should request the token dynamically. It is also possible to pre-create the token and embed it within the application. If you make a request to a secured service without a token, you will receive an HTTP response with a code of 403 (access denied).

Receiving an authentication token

The ArcGIS Token Service is usually available at the URL

 

https://{Business Analyst Server host name}/{ArcGIS instance}/tokens

 

Example:

 

https://localhost/ArcGIS/tokens

 

Once you know the token service URL, you can request a token, assuming you have a valid user name and password for ArcGIS Server instance. The request for a short-lived token contains the following query parameters:

 

request — request type. Its value is always getToken

username — name of a valid user

password — user's password

 

Request example

https://localhost/ArcGIS/tokens?request=getToken&username=MyUser&password=MyPassword

 

NOTE: For convenience of reading, the URI request query is split in a number of lines—one line per a query parameter.

 

If user credentials are correct, a short-lived token string is returned:

 

Response

pxgX12SIpL0obpUxhlylld_JQSu9ldG3-PqguagFEagDIN_WwC5ZMVGF0KDuizoC

 

If incorrect credentials are sent, or HTTP was used when HTTPS was required, an HTTP response code of 403 (forbidden) will be received.

Receiving long-lived authentication token

The token has an expiration timeout. The timeout determines the time period that the token will be valid.

 

In order to obtain a long-lived token, you must also specify a client ID and an expiration timeout in the query string:

 

clientid — client ID. It is either the client IP address, or the Web Referrer URL, which is the URL of the web application that the client browser is using.

timeout — expiration timeout. If no timeout is specified, the timeout specified for short-lived tokens is used.

 

Request example

https://localhost/ArcGIS/tokens?request=getToken&clientid=ip.10.212.22.55&timeout=1440&username=MyUser&password=MyPassword

 

The clientid parameter is an identifier for the client. Use a "." character between client ID type and value. Type may be either (a) ip, where an IP address of the client is specified, or (b) ref, where an Web Referrer URL is specified. The timeout value is specified in minutes. In the example above, a one-day expiration timeout is requested.

Using token-based security with Business Analyst Server REST endpoints

The token will be a long string of characters. It must be specified in the token parameter value of a Business Analyst Server REST endpoint.

 

Request example

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/DriveTime/execute?token=pxgX12SIpL0obpUxhlylld_JQSu9ldG3-PqguagFEagDIN_WwC5ZMVGF0KDuizoC&
...

 

NOTE: Other parameters of the DriveTime task are abbreviated where "..." is noted.

 

The token expiration timeout window may vary from a few minutes to several days. Currently there is no programmatic method to ascertain the token timeout. Therefore you must account for token expiration in your code, and obtain a new token when required.

 

Currently the way to detect timeout of a token is to catch the exception thrown and to check the response code. A code of 498 indicates an expired or otherwise invalid token. A code of 403 or 499 indicates that a token is required (if no token was submitted). Once you determine that a new token is needed, you can request one, update Business Analyst Server REST endpoint request URI with the new token, and repeat the request.