Imprivata OneSign Extension Objects

Extension objects allow Imprivata OneSign to extend beyond its base capabilities to support external software tools. You assign Imprivata OneSign Extension Objects to computers by means of computer policies, which are detailed in Creating and Managing Computer Policies.

NOTE: Imprivata OneSign extension objects are unrelated to the Imprivata OneSign extension that is installed in Google Chrome to enable single sign-on. See Support for Applications that Run in Google Chrome.

Imprivata OneSign supports three extension objects, available from the Extensions tab of the Computer policy page in the Imprivata Admin Console:

Imprivata is a Carefx Infrastructure Partner, and Imprivata OneSign is fully integrated with the Carefx Fusion Context Channel software and Fusion Context Manager CCOW solution.

Fusion Context Channel connects Imprivata OneSign to Fusion Context Manager. When users authenticate to Imprivata OneSign, Imprivata OneSign authenticates them into the full Fusion Context Manager experience. This works on all computers that have a Fusion client installed and an Imprivata agent installed. It does not matter which kind of Imprivata agent is installed.

No scripting or other modifications are required. To use Imprivata OneSign with Fusion Context Channel and Fusion Context Manager, just enable the Carefx extension object.

NOTE: You can enable or disable the Carefx extension object in a computer policy, but you cannot edit it.

Imprivata OneSign integrates with Fusion Context Manager by synchronizing the context manager with the user ID. When a user logs into a computer with an Imprivata agent and a Fusion client installed, if the Carefx extension object is enabled, then Imprivata OneSign runs a Carefx synchronize action with Fusion Context Channel. The synchronize action then sets the user ID into the CCOW context.

Imprivata and MEDITECH, working together with Forward Advantage, have produced a OneSign extension object designed to manage exit functions from MEDITECH applications when switching users on a shared workstation.

NOTE: This extension object only applies if you are providing SSO to MEDITECH applications through OneSign Single Sign-On.

Imprivata OneSign procedure codes are command sequences or more complex JavaScript or VBScript scripts triggered by pre-defined agent and application events.

When you create Imprivata OneSign procedure code, you use a chooser to select events that will trigger the code, and then write the code in an edit box beneath the events chooser. The agent and application events and Imprivata OneSign variables are provided in live glossary links.

You can define single events, use an OR function to define alternative events, and use a PAUSE/EXCEPT combination to define a canceling event.

NOTE: Microsoft has announced the deprecation of VBScript. Microsoft has not announced a release date on which VBScript will be retired, instead stating that VBScript will be available as a feature on demand before being retired in a future Windows release. While Imprivata procedure code extension objects continue to support VBScript, it is recommenced that you create new event triggers using a supported scripting language, such as JavaScript, while planning for the retirement of VBScript.

A VBScript to map to a specific drive depending on who logs into a workstation: Each time a user logs into the workstation, the script executes to ensure the user has access to the correct network drive. In this example, the user login is the event, and the mapping is handled by a VBScript created by an Administrator.

A VBScript to unmap the drive when the user logs out or is disconnected: When any user logs out of the workstation, the desktop locks and the drive mapping is deleted. In this example, the desktop lock is the event, and the mapping and unmapping is handled by a VBScript created by an Administrator.

You create, edit, and delete procedure codes from the View/Edit link of the Procedure code section of the Extensions page from the gear icon.

Creating a Procedure Code

To create a new procedure code:

  1. Click Add.

  2. Specify the conditions under which the procedure code is to be executed . See Specifying the Conditions.

  3. Enter the code. See Entering the Code.

  4. Select the Execution Method and Save

Editing a Procedure Code

To edit an existing procedure code, click on its name and make your changes just as if you were creating a new procedure code.

Deleting a Procedure Code

To delete one or more procedure codes:

  1. Select the names of the codes to be deleted.

  2. Click Delete.

The first step when setting up a procedure code is to specify the conditions that trigger it. Conditions are built from events arrayed in a logic tree as shown in the following image:

Events that occur at the agent level, regardless of what applications may be running, are global events. Events that are triggered by an application starting or shutting down, or by a specific window within a specific application, are application events. Application events are supported in OneSign SSO only.

To specify conditions that will trigger a procedure code:

  1. Select a global event to trigger the procedure code, or scroll to the bottom of the Global Events list and select Application Events to open a drop-down list that shows all profiled applications. When you select an application, a new drop-down list opens showing application events. Select an application event to trigger the procedure code. Application events are available only with the SSO option.

  2. If the event should always trigger the procedure code, then enter the code.

  3. If there are additional events that may trigger the same code, then click Or and select additional global and application events as needed.

  4. To enter an exception that can cancel the procedure code, click Pause... and enter the pause duration in seconds, and then fill in the Unless conditions in the same way. Execution of the procedure code is delayed for that period (counting from the triggering event) while the agent watches for the canceling event to occur:

    • If the Pause time elapses without the canceling event taking place, then the procedure code is executed.

    • If the canceling event occurs, then the procedure code is not needed.

Procedure codes are triggered by events. Use the Events Glossary to be certain of the events that will trigger the procedure code. There are two types of events:

  • Global Events for Procedure Codes — The global events in the following table are triggered by Imprivata agent activities and apply without regard to any running applications. Global events are useful for Procedure Codes invoked by user or computer workstation actions.

  • Application Events for Procedure Codes (SSO Only) — The application events in the second table are triggered by OneSign-recognizable events from specific applications. Application events are monitored only when you have OneSign SSO installed.

Global Events for Procedure Codes

Global Event Agent Type Event Trigger

Agent Startup

All

Only when the agent process is started. This may happen because of the Autorun key in the registry, or because of a manual startup of the agent. Before this event is fired, the agent has no logged-in user.

Agent Shutdown

All

Right before termination of the agent process. This is fired when the user chooses to exit the agent or when the user chooses to log off. At the time when this event is fired, there may or may not be a logged-in user.

User Login

Kiosk agent

Immediately after a new user unlocks the workstation. The event is also fired just after any authentication where the new user is different from the previous user.

Imprivata single-user computer agent and Citrix agent

Imprivata shared kiosk workstation agent

Immediately after a session is started for the user. This event fires sometime after the AgentStartup event, when the agent picks up the session. At the time this event is fired, a user is logged in. The user may be online or offline depending on the state of the communications with the Imprivata server.

This event is also fired just after any authentication where the new user is different from the previous user.
User Logout Imprivata single-user computer agent and Imprivata shared kiosk workstation agent Inactivity or timer-based challenges, hotkey press, tap to lock, and a logoff initiated from either the ISXAgent menu or ISXMenu.exe.
Imprivata Citrix or Terminal server agent N/A

Non-OneSign User Login

All

When a user logs into Windows without OneSign authentication (if allowed in Computer Policy).

Login Dialog Cancelled

Citrix or Terminal server agent, Imprivata shared kiosk workstation agent

When the login dialog for the agent is canceled.

NOTE: The Imprivata single-user computer agent does not send this event.

Desktop Locked

Imprivata single-user computer agent and Imprivata shared kiosk workstation agent

At additional finger enrollment, random challenge, offline/online transition with an expired session, offline/online transition with non-offline support policy set, inactivity challenge, hotkey press, and Lock event. At the time this event is fired, there may still be a logged-in user.

Citrix or Terminal server agent

N/A (the desktop does not get locked for a Citrix agent under such conditions)

Desktop Unlocked

All

After a returning user unlocks a locked desktop.

Remote Session Connected

All

When a user logs in to a remote virtual desktop session.

Remote Session Disconnected

All

When a remote virtual desktop session is disconnected.

Lock Warning (Inactivity) Indicated

All

Occurs when a lock warning (inactivity) indicator is displayed.

Connection Lost

All

During all online/offline transitions. When this event is fired, there should always be a logged-in user.

Connection
Reestablished

All

During all offline/online transitions. When this event is fired, there should always be a logged-in user.

Application Events for Procedure Codes (SSO Only)

Application Event Application Type Event Trigger

Application Startup

HLLAPI

When a new application is recognized within a HLLAPI session. When this event is fired, a logged-in SSO user exists and application variables may have captured values.

Windows apps, Java

When a new application is recognized. When this event is fired, a logged-in SSO user exists and application variables may have captured values.

TEs, WEB

When a terminal emulator container is started.

Application Shutdown

Windows apps, Java

When the main window of an application is about to be closed.

TEs, Web

When a terminal emulator container is closed.

Screen Appeared

Windows apps, Java

When a profiled screen is recognized in an active window.

Web

Upon navigation to a monitored URL.

Capturing Credentials

Windows apps, Java, TEs, Web

When the agent changes to Credentials Capture mode. This change of mode corresponds to display of the notification bubble with the "Capturing Credentials" text.

Credentials Captured

All

When the agent exits Credentials Capture mode. This change of mode corresponds to the display of the notification bubble with the "Credentials Captured" text. Note that this event may not be fired following a Capturing Credentials event if success screen is not seen.

Credentials Proxied

All

When credentials are proxied to a screen.

Password Change Begin

All

When a password change screen is found and credentials are about to be captured on the screen. This change of mode corresponds to the display of the “Capturing Credentials” notification bubble.

Password Change Complete

All

When credentials are successfully captured on a password change screen.

The procedure code can be BAT files and commands to be executed from the command line, or more complex scripts written in JavaScript, VBScript, or WSH, supplemented with Imprivata variables.

NOTE: While procedure codes continue to support the use of VBScript, Microsoft has announced their deprecation. It is recommenced that you create new event triggers using another supported scripting language, while you plan for the retirement of VBScript.

The following image shows an example of the Edit Procedure Code -- Webpage Dialog:

The Variables Glossary

When you enter the procedure code, use the Imprivata variables available from the Variables Glossary.

NOTE: Imprivata OneSign APG keystroke codes are not usable with procedure codes.

Select if the procedure code is to be executed from the command line or saved to a file as shown in the following image:

  • Procedure codes run from the command line must use DOS commands, which are limited to a single line of code.
  • Procedure codes saved to a file can be complex scripts written in JavaScript or VBScript. These procedure codes are saved in a TEMP folder only until executed. At runtime, the variables are replaced with in-memory values. At runtime the code is temporarily saved to disk for execution and then deleted when execution terminates.
  • The Imprivata agent uses the Windows Shell to open the saved file for execution, relying upon the file extension to identify how to execute it.
  • The procedure code cannot be used until it is enabled in a computer policy; see Enabling Extension Objects in Computer Policies.

The shared secret generates an 256 bit AES encryption key used to establish trust between the Imprivata appliance and the third party application.

Details of the encryption key:

Salt: SSOENCPWD

Algorithm: AES256

Key size: 256 bits

Block size: 16 bytes

Cipher mode: CBC

Padding: PKCS#7

You must also enter this secret in the third party application.

To set the shared secret:

  1. Click Set.

  2. Enter and confirm the shared secret. The shared secret should be between 8 and 128 characters in length.