TN 3825: iLab Integration

Configuration of dedicated KeyServer for iLab integrated control of laboratory equipment software.

Overview

When using Sassafras KeyServer with iLab, the system can not be used with non-iLab machines. The integrated "authentication" used to communicate with iLab precludes standard deployment of KeyServer. Many of the same setup concepts still apply however. Customers will want to review the general Deployment Outline as these basic setup principles still apply.

Customers interested in using KeyServer in typical deployments should contact Sassafras Sales regarding a second license for a general purpose KeyServer.

Configuration

The main step in setting up iLab integration is setting the Client Authentication in KeyConfigure under the Config menu. Choose the iLab option under the Method pull down at the top and set your Pattern URL to:

http://IPADDRESS_HERE/authenticate?group=$g&computer_id=$i

using the IP of the Bridge per the iLab Setup Documentation. The Bridge is a linux based server in your environment that serves as a link between iLab's hosted system and your internal equipment and the Sassafras server.

Policies

As is typical with KeyServer, Policies control access to software. The unique situation with iLab is that instead of a Policy observing or managing one software Product as used in the entire environment, a Policy can control all software used on a single computer. While this is usually a 1:1 ratio, there are instances where customers run multiple pieces of software on a given computer hooked to a given piece of lab equipment. Each piece of equipment is given an Interlock Group ID in the iLab web interface. This ID is used in the Scope of the Policy in KeyServer. On the other end, the Computer ID from KeyServer for that system is put into the Interlock. This creates a two way identification of the computer, and enables the Policy to control what that system can run as confirmed by the communication with iLab for that ID. It's also possible though less common to create separate schedules and therefore separate group IDs for each piece of software to have a many to one relationship in the other direction. However this creates a challenge of the two schedules not overlapping as it's for the same system. Agilent support can assist with this complexity if needed.

Note: The query made from Sassafras KeyServer to the iLab Bridge is a simple http request. Based on the response (200, 500, 404) we determine a pass or fail condition for that group ID being valid to start the software. There is also a query from the Bridge to KeyReporter when attempting to end a session to determine if the software is still running. If it is, then iLab will not allow the session to end until the program is quit on the client, assuming the Bridge is configured for the proper KeyServer address. This is why the KeyReporter service needs to be configured and running on KeyServer, even if the standard features of that component are not used. This means that http communication needs to be open between the two servers with these services.

Two polices need to be made for any given relationship. One is a Manage Policy that allows that iLab ID to run a given Product or Products. The other is a universal Deny policy that prevents all other machines from running said Product. Additional Deny policies can be created to prevent users from launching applications other than the intended software on the workstation(s). Each computer that is hooked to a piece of equipment must have a Manage policy that dictates the Product(s) allowed to run as controlled by the iLab integration. To emphasize this, if you manage one application that is used on 4 computers (each a workstation with given lab equipment), you would have 1 Deny and 4 Manage policies, each of which specifies a single Product. Without these policies there is no management and the software will work openly in the environment.

Tip - Because of these unique relationships, it can be helpful to name the Manage policies for the equipment or workstation name (as commonly known in your setting) for easy reference. The Deny Policies conversely you may want to name for the Product they are preventing, as is typical with KeyServer Policy naming.

Interlocks

As mentioned the configuration of the iLab integration is two way. While the Policies in KeyServer need to reference the ID of the Interlock in iLab, the Interlock in iLab needs to reference the Computer ID from KeyServer. In a normal deployment Policies would scope to computers for a specific node based control, but the iLab ID takes this role in this integration. However the KeyAccess client on the workstation is communicated with by way of the unique Computer ID in KeyServer. As such there is no direct relation between the Policy and Computer, it is iLab in the middle that make the site policy act in a restricted way via the unique scope.

See also iLab's documentation on Managing Interlock.

Tip - For ease of reference name your computers in a way you can easily find in the Computers window in KeyConfigure. If this is not possible due to standard naming in your environment, you may want to use one of our Custom fields to set a "Common Name" and display that column along with the Computer ID column. This will allow you to easily locate the desired workstation hooked to a piece of equipment, and get the ID to put into the Interlock configuration in iLab.

Troubleshooting

In a properly configured environment, when an application is launched on a workstation KeyAccess checks with KeyServer if it's allowed to run. KeyServer locates Policies scoped to a Product containing the Program and tries to resolve if it's allowed to run. With no Policy, the software is free to launch. If it finds there is a Deny but also a Manage that might allow it, then it tries to determine if the computer in question is in the Policy scope. As the scope is an iLab ID, it uses the authentication module configuration to talk to the iLab server and query the status of that ID. We obtain a single pass or fail response based on the ID existing and being authorized by schedule at that time.

This process means there are several easy tests you can run to verify things are working as expected. If there is no scope in a Manage policy, everything should be denied. If it's not, that indicates the Deny Policy or the Product it controls are not configured properly. See our blog post on Creating Accurate Product Definitions for tips on this aspect.

If there is a scope on a Policy and the software launches on the workstation, you should see a 1 in the In Use column for that Policy in KeyConfigure. If not, it again indicates that the Product is not properly configured to contain that Program, so the software is being allowed to run because nothing is denying it. You should also verify the KeyAccess agent is actually installed and running on the client computers. Without that service running, nothing will be controlled, so you should consider restricting admin rights in your environment.

If the software runs, and you see use on the Policy, everything is technically working as expected. However, if this happens without an active session in iLab (meaning you'd expect to be denied anyway), it indicates there is an issue in the calendaring of iLab and you should contact Agilent support for assistance. One common cause of this is setting the equipment to the ON state in the interlock. That is an override to the schedule that makes is available for use.

On a related note, do NOT use the Groups window in KeyConfigure with iLab. If you create groups of the same name as the iLab ID, this will override checking with iLab and instead use the local group configuration. This breaks the intended functionality in various potential ways.

If you believe everything is configured properly but are still being denied, the first step is to disable the Deny Policy you expect to be doing the deny operation. There is an Enabled checkbox in the Policy Details for this. If disabling the Deny does not stop the Program from being denied, another Policy is in play. You can run a Session Dump Report targeted to the computer in question and look at the deny events. The Policy causing the deny will be listed and you can troubleshoot your Policy or Product definition from there.

A more advanced troubleshooting step is to go into KeyConfigure -> Config -> Log File Management and turn the Authentication level to Verbose. Note you'll also need to set the global Level at the top to Verbose to allow that level. Also turn on the checkbox for Write to Disk Immediately. Run another test and then look at what is recorded in the diagnostic.log in the KeyServer Data Folder on the server. You should see a URL that can be tested in a browser to confirm what response is being received. If a page loads (http 200) that is a "yes" success. If you get a 404, 301, or other error response, that is a "no" failure.

As always please contact support if you need assistance.