Our Check out feature requires an identity lookup service to handle the translation of Badge IDs to User IDs. Imprivata Enterprise Access Management (formerly Imprivata OneSign) is the easiest service for this.
If you do not have Imprivata Enterprise Access Management, you must 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 article specifies the input and output your web service must use.
NOTE: Password AutoFill is only supported with Imprivata Enterprise Access Management.
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 MAM (GroundControl) server.
- User “Alice” taps her ID badge on a reader
- The Launchpad software reads the hexadecimal ID “A1B2C3D4” from the badge
- The Launchpad software sends an HTTP request to your Identity Lookup Web Service
- 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”
- Your Identity Lookup Web Service formats the data as JSON, and prints this data as the HTTP response.
- The Launchpad forwards the User ID to the MAM 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:
http://10.1.1.1/lookup.php?id=A1B2C3D4
and return a user ID in JSON format, such as this:
{ "user" : "alice" }
A typical implementation uses a virtual machine running Windows or Linux. The VM runs a web server, scripting language and possibly a database backend. Imprivata encourages you to use the systems and scripting languages most familiar to your staff.
Shared Hosting: MAM 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 reasons.
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 Enterprise Access Management (OneSign): For addition information, see Integrate Imprivata Enterprise Access Management.
Imprivata Identity Governance: Identity Governance allows direct LDAP lookups when set up with a system-level password. Your Web Services script can directly query Identity Governance to loop up badge IDs.
Contact Imprivata 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
MAM sends 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 MAM to use.
For example, any of these formats are acceptable:
- http://10.1.1.1/lookup?id=[DATA]
- http://10.1.1.1/lookup?card=[DATA]
- http://10.1.1.1/path/to/script.php?id=[DATA]
- http://identities.company.com/lookup?id=[DATA]
- http://10.1.1.1/lookup/[DATA]
- http://10.1.1.1/lookup?id=[DATA]&pw=abc123
- http://user:password@10.1.1.1/lookup?id=[DATA]
- https://10.1.1.1/lookup?id=[DATA]
- https://10.1.1.1:4430/lookup?id=[DATA]
MAM automatically substitutes 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. Reach out to Imprivata Support for more information.
- HTTPS Trust: If HTTPS is used, the HTTPS certificate must be trusted by MAM. A self-signed certificate may not function correctly.
- Encoding: MAM sends the raw data in hexadecimal. You may need to covert to decimal as part of your lookup routines.
HTTP Response Details
MAM 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 MAM attribute names, the data will be available to MAM 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 MAM reads. If you have been following the Check out 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 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 access the URL of your Web Service. Use the badge ID MAM 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 MAM. In Admin > Checkout, change the Identity Web Service to Custom.
MAM displays a dialog for you to enter your system’s URL.
After you save this, you’ll need to restart any Launchpads for the change to take effect. Test the badge integration.