| FRAMES | NO FRAMES |
Business Analyst Server Web services may be secured to permit only authorized users. Business Analyst Server implements security in the SOAP by using the 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. The token is appended to the query string of a Web service URL. 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).
Using Catalog Web Service
To determine whether the server accepts or requires tokens, you can use the RequiresTokens method of the Catalog Web Service. The Catalog Web Service WSDL syntax is the following:
https://{Business Analyst Server host name}/{ArcGIS instance}/services?wsdl
Example:
https://localhost/arcgis/services?wsdl
To work with Catalog Web Service SOAP, you must add a Web Reference to its WSDL in the same manner as described in Add a reference to a Esri Business Analyst Server Web Map service.
If the RequiresTokens method returns true, you can then obtain the URL of the token service with the GetTokenServiceURL method.
| C# |
Catalog catalog = new Catalog(); catalog.Url = "http://localhost/arcgis/services"; string tokenServiceUrl = catalog.RequiresTokens() ? catalog.GetTokenServiceURL() : null; |
Receiving an authentication token
The 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. You can use the WebRequest class to make a request for the token. Note that the request may encounter problems such as an unresponsive server, incorrect password, etc. You can wrap the request in a try-catch block to deal with errors.
| C# |
string tokenServiceUrl = "https://localhost/arcgis/tokens"; UriBuilder uriBuilder = new UriBuilder(tokenServiceUrl); uriBuilder.Query = "request=getToken&username=myuser&password=secret"; System.Net.WebRequest request = System.Net.WebRequest.Create(uriBuilder.Uri); string myToken = null; string errorMsg = null; try { System.Net.WebResponse response = request.GetResponse(); System.IO.Stream responseStream = response.GetResponseStream(); System.IO.StreamReader readStream = new System.IO.StreamReader(responseStream); myToken = readStream.ReadToEnd(); } catch (System.Net.WebException ex) { if (ex.Message.Contains("403")) errorMsg = "Server returned forbidden (403) code." } |
If incorrect credentials are sent, or HTTP was used when HTTPS was required, an HTTP response code of 403 (forbidden) will be received. This will be in an exception thrown as shown in the sample code above. Otherwise, the token may be read from the response.
Receiving long-lived authentication token
The token has an expiration timeout. The timeout determines the time period that the token will be valid. In the sample code above, a short-lived token was created.
In order to obtain a long-lived token, you must also specify a client ID and an expiration timeout in the query string. The client ID 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. If no timeout is specified, the timeout specified for short-lived tokens is used. The sample code below shows how to specify the query string in order to obtain a long-lived token.
| C# |
UriBuilder uriBuilder = new UriBuilder(tokenServiceUrl); string clientIP = "10.212.22.244"; // Insert your IP address here string timeout = "1440"; // Specify the timeout in minutes. This is one-day timeout string username = "myuser"; // Insert user name here string password = "secret"; // Insert password here uriBuilder.Query = string.Format("request=getToken&clientid=ip.{0}&expiration={1}&username={2}&password={3}", clientIP, timeout, username, password); |
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.
Updating Business Analyst Server Web Service URL
The token will be a long string of characters. You do not need to include it within the request itself, but it must be appended to the URL of the web service endpoint:
| C# |
DefaultMap_BAServer baServer = new DefaultMap_BAServer(); UriBuilder uriBuilder = new UriBuilder(baServer.Url); uriBuilder.Query = "token=" + myToken; baServer.Url = uriBuilder.Uri.ToString(); |
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 the server's URL with the token, and repeat the request.
When token-based security is enabled, you will not be able to view or access the Business Analyst Server WSDL using the standard URL:
http://{Business Analyst Server host name}/{ArcGIS instance}/services/{Map service with Business Analyst capability}/mapserver/BAServer?wsdl
Example:
http://localhost/arcgis/services/DefaultMap/mapserver/BAServer?wsdl
Without access to the WSDL, you will not be able to consume it or create a new or update an existing SOAP proxy class in your development environment.
With token-based security enabled, the WSDL can be accessed by generating and appending an unexpired token string to the WSDL URL before making a request. The following steps describe one way to securely obtain a token for the WSDL URL.
Use the following URL in a Web browser or client with HTTP over Secure Socket Layer (HTTPS) capability (the request will be encrypted):
https://{Business Analyst Server host name}/{ArcGIS instance}/tokens?request=getToken&username=<user name>&password=<password>
Example:
https://localhost/arcgis/tokens?request=getToken&username=myuser&password=secret
This will generate a unique token string which will expire in a few minutes.
Copy the entire string value returned and append it to the WSDL URL as a value for the token parameter:
http://{Business Analyst Server host name}/{ArcGIS instance}/services/{Map service with Business Analyst capability}/mapserver/BAServer?wsdl&token=<token string>
Example:
http://localhost/arcgis/services/DefaultMap/mapserver/BAServer?wsdl&token=5fg2rgARRshpWHSzYAHWgPaNzJLaDKg5R5oVXhk55gA
If you navigate to this URL in a Web browser or client before the token expires, you will be able to view the WSDL.
In order to generate or update the SOAP proxy class in your development environment, you will need to perform a similar set of steps. Use the WSDL URL with the unexpired token string in order to create a SOAP proxy class. If the token string has expired, a new one must be created.
NOTE: It is important to understand that, in the context of developing with the SOAP, the WSDL is only needed to generate the proxy class between the development environment and the Business Analyst Server instance. Unless the Business Analyst Server proxy class in your development environment needs to be explicitly updated or associated with another Business Analyst Server instance, you no longer need to generate any unexpired token strings to append to the WSDL URL after the proxy class has already been created.
When calling the SOAP proxy class methods, you will have to associate the method calls with an unexpired token string. This time, since you already have a SOAP proxy class to work with, you will be able to generate and utilize token strings in your application programmatically using the built-in token service.
You can download an auxiliary BAServerHelper package in order to become familiar with a full-functional token providing solution used with the Business Analyst Server. See Using BAServerHelper Class for details.
Esri Business Analyst Server implements security for the SOAP using a token-based authentication scheme derived from core ArcGIS Server. For more information on token-based security, you can refer to ArcGIS Server documentation: