Using OAuth 2.0 to access Location Hub

Location Hub uses Web Service authentication for authorization and access based on OAuth 2.0 protocol. Microsoft Azure Access Control Service (ACS) is used as the authorization server to obtain a token. All information transmitted to Location Hub services is encrypted using Secure Socket Layer (SSL) technology.

The Location Hub® Viewer API utilizes Basic Authentication for authorization and access of the services. Please refer to the Basic Authentication page for more details.

Basic Workflow

To summarize, the workflow is as follows:
  • Request an access token from the Authentication server using the client application’s credentials. Please contact your account executive to obtain your client credentials (Authentication ID and Password).
  • Cache the authentication token for use in all requests until it expires.
  • Use the authentication token to make requests to Location Hub, until the authentication token expires. When the token has expired, the process should be repeated.

Requesting a Token

Tokens are retrieved using a simple HTTP POST request and then the token is appended to each service request in the “Authorization” HTTP header. The POST request requires the following three parameters:
  • wrap_scope - The endpoint url of the Location Hub service being called
  • wrap_name - The Authentication ID provided by your account executive
  • wrap_password - The Authentication Password provided by your account executive

Sample HTTP POST Request

Accept-Encoding: gzip,deflate
Content-Type: application/x-www-form-urlencoded
Content-Length: 151
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Sample HTTP POST Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/x-www-form-urlencoded; charset=us-ascii
Expires: -1
request-id: a974dee5-ecdb-4f83-8e01-52661753212a
X-Content-Type-Options: nosniff
Date: Mon, 26 May 2014 19:22:08 GMT
Content-Length: 498

Sample Token Management Code (C#)

private string authBaseAddress = "";
private string authID = "AuthenticationID";
private string authPassword = "AuthenticationPassword";
// wrapScope is the Location Hub Service Endpoint url (eg. Address Recognition Endpoint below)
private string wrapScope = "";
Dictionary<string, KeyValuePair<string, DateTime>> tokens = new Dictionary<string, KeyValuePair<string, DateTime>>();
public string GetToken(string wrapScope)
    lock (tokens)
        KeyValuePair<string, DateTime> tokenPair;
        if (!tokens.TryGetValue(wrapScope, out tokenPair) || tokenPair.Value < DateTime.UtcNow)
            var acsResponse = GetTokenFromACS(wrapScope);
            if (acsResponse != null)
                // the returned token must be wrapped with double quotes and is preceded with "WRAP access_token="
                string authToken = string.Format("WRAP access_token=\"{0}\"", acsResponse.Value.Key);
                // request new token when we are at 20% from the expiration time
                DateTime tokenExpiry = DateTime.UtcNow.AddSeconds(acsResponse.Value.Value * 4 / 5);
                tokenPair = new KeyValuePair<string, DateTime>(authToken, tokenExpiry);
                tokens[wrapScope] = tokenPair;
        return tokenPair.Key;
private KeyValuePair<string, int>? GetTokenFromACS(string wrapScope)
    WebClient acsClient = new WebClient();
    acsClient.BaseAddress = authBaseAddress;
    NameValueCollection values = new NameValueCollection();
    values.Add("wrap_scope", wrapScope);
    values.Add("wrap_name", authID);
    values.Add("wrap_password", authPassword);
    byte[] acsResponseInBytes = acsClient.UploadValues("WRAPv0.9", values);
    string acsResponse = Encoding.UTF8.GetString(acsResponseInBytes);
    string[] responseValues = acsResponse.Split('&');
    return new KeyValuePair<string, int>(
        responseValues.Single(value => value.StartsWith("wrap_access_token=", StringComparison.OrdinalIgnoreCase)).Split('=')[1],
        int.Parse(responseValues.Single(value => value.StartsWith("wrap_access_token_expires_in=", StringComparison.OrdinalIgnoreCase)).Split('=')[1])

Using the Token

Once you have received the token and cached it, you can use the cached token in all calls to Location Hub by including it as the HTTP Authorization header. Attaching the token as the Authentication header can be done using the example below:
string wrapScope = "";
var token = GetToken(wrapScope);
if (token != null)
        = token;

The HTTP POST request would look something like this:
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "RecognizeFreeForm"
Authorization: WRAP access_token="Customer%3D<AuthenticationID>"
Content-Length: 1809
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Token Expiry

When a token is issued, the expiry time is included in the token response as the actual expiry date and time in UTC time standard. The number of seconds from the time of issue is also included. The default token expiry time is 8 hours form time of issue.

The token expiry is defined in the following response parameter:
  • ExpiresOn: The exact Coordinated Universal Time (UTC) date and time that the token will expire
  • wrap_access_token_expires_in: The number of seconds from the time of issue that the token will expire

It is recommended that you request a new token before the expiry time.