Geo-Fencing using Pitney Bowes ReverseGeocode API


Latitude. Longitude. They’re a way of reaching consumers based not just on transactional data, but also where they are at any given moment. It is possible to protect data by reaching consumers on the go. Precision Reverse Geocoding, only from Pitney Bowes Software, uses a smartphone’s GPS signal to pinpoint a consumer’s location. That location can then be used to determine proximity to secured data zones and even cross-referenced with nearby mobile users within an individual’s social network. Details can be found at Pitney Bowes Geocoding.

While location coordinates can be used for increasing sales and relevance in the Retail and Fast Moving Consumer Goods industries, there are authentication and authorization use cases for the security market as a whole that could use geo-fencing. This technology could enable an organization to protect data from unauthorized access by ‘enveloping’ it with an authorization protocol based on geo-location. Devices that are able to transmit geolocation to OpenAM using either the built-in GPS, or by other means, may then be checked for authorized access based on the current user location before access to data is permitted. This can be accomplished simply by using a scripted authentication connector in OpenAM and the Pitney Bowes ReverseGeocodeUSLocation API.


For the purpose of this demo, we will use a scripted authentication module in OpenAM with the client side script supplying the latitude and longitude, as shown here:

When the user hits the OK button, the coordinates are submitted to the server side script, which then makes an authenticated REST call to the ReverseGeocodeUSLocation Pitney Bowes API.

If the user is within the approved zone for this particular request for access, then she is granted permission to proceed, otherwise an authentication denied error is shown. In our case here, if the demo device is moved more than 15 feet away, our position coordinates change to the address of my neighbor, as shown here:

Since these one-shot coordinates map to a different street address than the one permitted, for this demo anyway, authentication is immediately denied:

If I stay within the approved zone when logging on to OpenAM from my device, the access attempt is approved.

Client Side Script

The client side script uses the Mozilla Geolocation API to retrieve the coordinates which are passed on to the server side script in the clientScriptOutputData JSON object. The implementation of the Geolocation API is based on the W3C Geolocation API Specification. The Geolocation API defines a high-level interface to location information associated only with the device hosting the implementation, such as latitude and longitude. The API itself is agnostic of the underlying location information sources. Common sources of location information include Global Positioning System (GPS) and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs, as well as user input. No guarantee is given that the API returns the device’s actual location. The API is designed to enable both “one-shot” position requests and repeated position updates, as well as the ability to explicitly query the cached positions. Location information is represented by latitude and longitude coordinates. For purposes of this demo, no special coding provisions were made to reject potentially cached position coordinates.

Server Side Script

The server side script extracts the coordinates, creates an HTTP Basic authorization header and calls the ReverseGeocodeUSLocation API. The API could easily be modified to permit HTTP Token or other forms of authorization. Note that in OpenAM 12 it is not currently possible to pass an HTTP authorization header and therefore a custom build was used to perform this integration. This facility will be available in OpenAM 13. The API returns the complete Census output fields containing U.S. Census information about the coordinates, including the precise street address. This street address is extracted from the returned message XML body, and checked with a known value. The demo keeps it simple, obviously. Much more could be accomplished with the data returned from the Pitney Bowes API. One could, for instance, during a “cut over” period, map the coordinates to create a heat-map, or user’s preferred area of usage. This zone could then be used to enforce any departures by denying access to requests for sensitive data outside it. Another use case could be co-relating the user’s one-shot position coordinates with nearby sensors and tags, to determine which building floor or room the user is currently requesting access to the data from, and taking policy actions based on that information.


The API defined in the W3C specification is used to retrieve the geographic location of a hosting device. In almost all cases, this information also discloses the location of the user of the device, thereby potentially compromising the user’s privacy. OpenAM’s use of Mozilla’s implementation of this specification provides a mechanism that protects the user’s privacy by ensuring that no location information is made available through this API without the user’s express permission. In this demo, by attempting a login into OpenAM, with implied access to secured and sensitized data, the user implicitly gives the permission for the location coordinates to be evaluated (shared with Pitney Bowes), however, no information identifying the user is sent over the wire.