TN 3825: iLab Integration

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

Overview

When using Sassafras KeyServer with iLab, integrations with other authentication methods is lost, which means wider asset management is not possible. The integrated "authentication" used to communicate with iLab precludes standard deployment of KeyServer. Attempting hybrid use is not supported as problems can arise. As such, if you use KeyServer broadly for asset management, a second server will be needed for iLab, and the workstations pointing to the iLab server can not be inventoried by the main server. 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. It should be understood that the KeyServer Suite of Products is a robust hardware and software asset management solution including a rich web component. The functions used for iLab are a tiny fraction of the capabilities, which is why things may seem overly complex for your specific use case.

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

Notice

One of the functions of iLab is supposed to be sending a kill signal to KeyServer if a session is terminated but the managed software is still in use. This feature in their platfrom has not been seen to work since at least 2019. We have been informed in 2024 that there are no active development resources allocated to iLab at Agilent. As such it's important to understand that a user may figure out they can end their iLab session and continue to use the managed software outside of the time tracking in iLab, which is what handles the billing in their platform. KeyServer keeps detailed usage records, so you can compare these before invoicing in iLab to ensure proper billing, both over and under. That is, iLab also has no knowledge of a scheduled session not being used, and while you may want to bill for unused booked time as no one else was able to book that time, you also may not want to bill for no wear on the managed hardware. These are issues to address with Agilent, we have no control over them. In order to use the reporting in KeyServer however, every user will need to log in to the managed computers with unique credentials (usually domain based). If you are using special equipment that is not multi user friendly and therefore all use is under a single local account, we will have no distinct user information as there are no distinct users. Customers are encouraged to understand these limitations of the integration and the current state of iLab before purchasing the softwares.

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 your 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 your 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.

Common Questions

What if the server/network go down? - This can be a concern if research needs to continue but the system controlling the equipment is unavailable. Because the intent of this system is to be secure and not bypassable for users, only an Administrator can bypass the system. To do so, simply use Admin rights to stop the KeyAccess service in Windows on the client workstation controlling the equipment. Without our agent running, nothing will be enforced. Obviously this is why users should not have Admin access, otherwise they can bypass the time tracking and related billing in iLab.

Can the Managed software be shut down when the Reservation ends? - Because a user may run past their scheduled time booked in iLab, it is often desirable to have the managed software terminated when that time ends. This is not however currently available as the required components for the Bridge to communicate this information have not been implemented. Contact Agilent for further inquiry.

Can the tracked time in iLab be tied to the running of the Software? - No. The reservation in iLab is what allows the software in the Policy to be launched while you have that right. It is not possible to flip that and have the session based on the software launch and quit. It could be possible with development in iLab to at least terminate a session soon after the software quits. It is possible in the KeyServer API to query the status of a Policy, so if Agilent were to implement a periodic check based on configurations and end a session that was previously active when the software is no longer in use, this would work. Contact Agilent for further inquiry.

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 it 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 may be 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. Another possibility is a corrupt policy due to changing the casing in the Scope setting. The iLab bridge is case sensitive, but KeyServer is not. If you typed in the scope as iLab-1234 it will not work. Changing to ilab-1234 will still not work because our software does not register this as a significant change. You may want to delete the policy(s) and remake them without typos.

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.