Integrate a Custom Identity Web Service

Mobile Access Management's Check Out feature requires an identity lookup service to handle the translation of Badge IDs to User IDs. Imprivata Enterprise Access Management (Imprivata OneSign) is the easiest service for this.

If you do not have EAM, 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 MAM (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 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 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: 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.

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 (Imprivata OneSign): For additional information, see Integrate Imprivata Enterprise Access Management'.

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. Mobile Access Management 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 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. Contact 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

Mobile Access Management 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's 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.

1. Copy a badge ID, in the hexadecimal raw MAM reads. If you have been following the Checkout setup instructions in this topic, then you may already have read one or more badges into the MAM User Identity Service. If not, here's a quick set of instructions.

   1. Set MAM Admin > Checkout to use Proximity Cards and the Mobile Access Management User Service for Identity.

      

   2. Plug in a proximity card 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.

   3. In Admin > Checkout, click Open Users to open the Mobile Access Management 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".

2. Use a web browser to browse to the URL of your Web Service. Use the badge ID Mobile Access Management just scanned as the [DATA].

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.

     

     Mobile Access Management displays a dialog for you to enter your system URL.

     Click to enlarge

     

4. After you save, restart any Launchpads for the change to take effect.

5. Test the badge integration.

Next

View a Device Checkout History