Integrate your Identity Web Service

Created: Modified: Checkout

When using our Checkout feature, GroundControl requires a web service at your organization. The web service will translate the employee badge’s raw identification to an employee username. This document specifies the input and output your web service must use.

As a simple example, a user with badge ID “A1B2C3D4” will attempt a check out. GroundControl can send the following to your server at 10.1.1.1:

http://10.1.1.1/lookup.php?id=A1B2C3D4

Your web service will return a JSON-encoded string such as:

{ "user" : "alice" }
Data Flow

  1. User “Tom” taps his ID badge on a reader
  2. The Launchpad software reads the ID from the badge
  3. The Launchpad software sends an HTTP request to your Identity Lookup Web Service
  4. Your Identity Lookup Web Service looks up the ID via an LDAP query, or AD bind, or other method
  5. Your Identity Lookup Web Service returns JSON-formatted data back to the Launchpad, including the Tom’s User ID
  6. The Launchpad sends the User ID to the GroundControl server to initiate the checkout process
Security

Although GroundControl is SaaS, 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.

HTTP Request

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. For example:

http://10.1.1.1/lookup.php?id=A1B2C3D4

would entered into GroundControl Admin > Checkout > Identity Web Service > URL as:

http://10.1.1.1/lookup.php?id=[DATA]

Note you could use any query string parameter to represent the badge ID, and also any path & filename.

  • HTTP Method: Only GET is supported.
  • Port: Ports 80 (HTTP) or 443 (HTTPS) may be used. If HTTPS is used, the HTTPS certificate must be trusted by GroundControl. A self-signed certificate may fail to function correctly.
  • Authentication: HTTP authentication is not supported. Custom headers are not supported.
  • Encoding: GroundControl sends the raw data in hexadecimal. You may need to covert to decimal as part of your lookup routines.
HTTP Response

We expect your service to return HTTP 200 and a JSON object, if successful, or HTTP 404 “Not Found” if not successful.

If successful, the minimum response is a key/value pair representing the user.

{ "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" }

Next: View a Device’s Checkout History