Integrate a Custom Identity Web Service

Created: Modified: Checkout

Our Checkout feature requires an identity lookup service to handle the translation of Badge IDs to User IDs. Imprivata OneSign is the easiest service for this. If you do not have OneSign, you will need to create a web service. We’ve tried to keep these requirements as simple and flexible as possible. Most organizations have the resources to fulfill these requirements in-house, so you should not need to hire outside help. This document specifies the input and output your web service must use.

Data Flow

This flow was designed to never expose raw badge IDs to the Internet. All queries with the raw Badge ID are kept inside your local network. Only the translated User ID is sent to the GroundControl server.

  1. User “Alice” taps her ID badge on a reader
  2. The Launchpad software reads the hexadecimal ID “A1B2C3D4” from the badge
  3. The Launchpad software sends an HTTP request to your Identity Lookup Web Service
  4. Your Identity Lookup Web Service (a) translates the hexadecimal ID to decimal, if required, and (b) queries the ID via an database lookup, LDAP query, or other method as appropriate, to retrieve the User ID “alice”
  5. Your Identity Lookup Web Service formats the data as JSON, and prints this data as the HTTP response.
  6. The Launchpad forwards the User ID to the GroundControl server to initiate the checkout process
The Identity Web Service

The Identity Web Service is a simple script that will take an HTTP call including the Badge ID, such as this:

and return a user ID in JSON format, such as this:

{ "user" : "alice" }

A typical implementation will use a virtual machine running Windows or Linux. The VM will run a web server, scripting language and possibly a database backend. We encourage you to use the systems and scripting languages most familiar to your staff.

Shared Hosting: GroundControl does not require a dedicated server for this function, but a dedicated server may be used.

Network Access: All requests will originate from inside your network, and use internal IP addresses. WAN access is not required, and should be avoided for security.

Obtain the Badge ID & User ID Data

Your system will need to have access to Badge IDs and User IDs. The way you obtain this data depends on your infrastructure.

Imprivata OneSign: Check out this article for more details on OneSign integration

Imprivata Caradigm: Caradigm allows direct LDAP lookups when set up with a system-level password. Your Web Services script can directly query Caradigm to loop up badge IDs. Please contact GroundControl Support for more information and sample code.

Active Directory: If your organization is lucky enough to store ID badges within Active Directory, it should be relatively easy for your web service to bind to AD, and query the Badge ID.

Other: The physical security division of many facilities is responsible for activating and deactivating badges for employees. GroundControl customers have had success integrating with these systems. This may be the easiest way to obtain data.

HTTP Request Details

GroundControl will send an HTTP GET request to your service. You can define the hostname (or IP address), HTTP or HTTPS, the path, and any query string. You will define a format for GroundControl to use. For example, any of these formats are acceptable:

  • http://user:password@[DATA]

GroundControl will automatically substitute the raw badge data, in hexadecimal format, wherever the [DATA] token appears in the URL you provide.

Here are some additional notes about the HTTP request:

  • HTTP Method: Only GET is supported.
  • HTTP Port: Any port may be used, if specified in the URL. By default, we will use port 80 for http and port 443 for https.
  • Authentication: There is support for Basic HTTP Authentication. Please reach out to GroundControl Support for more information.
  • HTTPS Trust: If HTTPS is used, the HTTPS certificate must be trusted by GroundControl. A self-signed certificate may not function correctly.
  • Encoding: GroundControl sends the raw data in hexadecimal. You may need to covert to decimal as part of your lookup routines.
HTTP Response Details

GroundControl accepts two status codes from the Identity Web Service:

  • 200 Success
  • 404 Not Found

If successful, the minimum response is a JSON key/value pair representing the user. The key “user” must be lower case, but the value can be any string.

{ "user" : "alice" }

If desired, your service may return additional key/value pairs. For example, the service may return “fullname” or “management_role”. If the key names match GroundControl attribute names, the data will be available to GroundControl as well, to be used in automation rules and/or workflows.

"user" : "alice",
"fullname": "Alice Liddel",
"management_role": "staff"
Testing your Web Service

Testing is easy. You can use a web browser to do it, once you have the right data.

Step 1: First you need to copy a badge ID, in the hexadecimal raw GroundControl reads. If you have been following the Checkout setup instructions in this documentation, then you may already have read one or more badges into the GroundControl User Identity Service. If not, here’s a quick set of instructions.

Set GroundControl Admin > Checkout to use Proximity Cards and the GroundControl User Service for Identity.

Now plug in a proximity badge reader into one of your Launchpads. Start the Launchpad app, then tap your badge. You may hear a single beep, followed by a double beep.

In Admin > Checkout click on Open Users to open the GroundControl User Service. Locate the badge ID just scanned, within the section Unknown PINs. This will be a short sequence of numbers and letters like this: “014793A2”.

Step 2: Use a web browser to “hit” the URL of your Web Service. Use the badge ID GroundControl just scanned as the [DATA].

Step 3: Examine the response — that is, the body of the web page shown. Hopefully, this will be a JSON object that includes the key “user”, such as the examples we have been showing.

If there was no match for the badge you used, then the web service may need to translate the badge ID from one format to another. For example, your web service may need to convert the badge ID from hexadecimal to decimal. (We’ve seen more complex conversions required too: one customer needed to convert by first converting the number to binary, converting the first 19 bits of the binary and last 19 bits to decimal, then concatenating (not adding) those two decimal numbers back together.)

If you received a successful match for the badge, and the format is valid JSON, then it is time to add the web service to GroundControl. In Admin > Checkout, change the Identity Web Service to Custom.

GroundControl will pop up a dialog for you to enter your system’s URL.

Once you save this, you’ll need to restart any Launchpads for the change to take effect. Go ahead and test the badge integration.

Next: View a Device’s Checkout History