Allowing an Application Window Atop the ProveID Embedded Lock Screen

To get the metadata field values from a log file, follow this procedure on one Imprivata ProveID Embedded endpoint:

1. Enable logging of application window activity.

   Set ProveID Embedded configuration option log-activity = True in the [windows.monitor] section of the Imprivata.conf configuration file.

   Either edit the file to add:

   [windows.monitor]

   log-activity = True

   or run this command from the system prompt:

   /usr/lib/imprivata/runtime/bin/configuration-editor windows.monitor --log-activity true

2. Launch the application that you want to appear above the Imprivata ProveID Embedded lock screen. This launch should add entries to the Imprivata ProveID Embedded agent log for that application.

3. Get or copy the Imprivata ProveID Embedded agent log file at location /usr/lib/imprivata/runtime/log/OneSignAgent.log.

4. Identify the metadata field values for the target application’s window in the log file.

   Window activity log items contain the string Agent.WindowsActivity. Look for string: Agent.WindowsActivity(_log,1277) - DEBUG: Create window call end.

   A complete line will look similar to this: 

   2021-09-03 10:31:53,723 - Agent.WindowsActivity(_log,1277) - DEBUG: Create window call end. ID:"58720259";WMClass:"Vncgui";WMName:"Shadowing on";WMAppInterface:"vncgui";

   The application window's WMClass, WMName, and WMAppInterface Windows metadata attributes and values are shown here in boldface. Note that an app window may not have all three attributes.

5. Make note of the metadata field values and go to Adding Metadata Field Values to the Admin Console and Rebooting Endpoints.

To get the metadata field values for an application window by using the xprop utility, follow this procedure on one Imprivata ProveID Embedded endpoint:

1. Run export DISPLAY=:0;

2. Run xprop;

   A special crossed cursor will appear on the screen.

3. Select the window of the application you want to appear above the lock screen.

   A full list of the window's attributes should be displayed, as shown in this example for an IGEL setup window:

   root@ITC00E0C5217062:~# export DISPLAY=:0

   root@ITC00E0C5217062:~# xprop

   _NET_WM_ALLOWED_ACTIONS(ATOM) = _NET_WM_ACTION_CLOSE, _NET_WM_ACTION_ABOVE, _NET_WM_ACTION_BELOW, _NET_WM_ACTION_FULLSCREEN, _NET_WM_ACTION_MOVE, _NET_WM_ACTION_RESIZE, _NET_WM_ACTION_MAXIMIZE_HORZ, _NET_WM_ACTION_MAXIMIZE_VERT, _NET_WM_ACTION_SHADE, _NET_WM_ACTION_MINIMIZE, _NET_WM_ACTION_CHANGE_DESKTOP, _NET_WM_ACTION_STICK

   WM_STATE(WM_STATE):

   window state: Normal

   icon window: 0xcce8f200

   _NET_WM_DESKTOP(CARDINAL) = 0

   _NET_WM_WINDOW_TYPE(ATOM) = _NET_WM_WINDOW_TYPE_NORMAL

   _MOTIF_WM_HINTS(_MOTIF_WM_HINTS) = 0x3, 0x1, 0x1, 0x0, 0x0

   _MOTIF_DRAG_RECEIVER_INFO(_MOTIF_DRAG_RECEIVER_INFO) = 0x6c, 0x0, 0x5, 0x0, 0x7, 0x0, 0x20, 0x4, 0x0, 0x0, 0x0, 0x0, 0x10, 0x0, 0x0, 0x0

   XdndAware(ATOM) = BITMAP

   _NET_WM_STATE(ATOM) = _NET_WM_STATE_FOCUSED

   WM_HINTS(WM_HINTS):

   Client accepts input or input focus: False

   Initial state is Normal State.

   _NET_FRAME_EXTENTS(CARDINAL) = 4, 4, 25, 4

   _NET_WM_ICON(CARDINAL) = Icon (32 x 32):_NET_WM_PID(CARDINAL) = 918159

   WM_CLIENT_MACHINE(STRING) = "ITC00E0C5217062"

   WM_PROTOCOLS(ATOM): protocols WM_DELETE_WINDOW, WM_TAKE_FOCUS

   WM_CLASS(STRING) = "sun-awt-X11-XFramePeer", "IGEL Setup"

   WM_CLIENT_LEADER(WINDOW): window id # 0x4200008

   _NET_WM_ICON_NAME(UTF8_STRING) = "IGEL Setup 11.05.133.01 (Build 6.7.5)"

   WM_ICON_NAME(STRING) = "IGEL Setup 11.05.133.01 (Build 6.7.5)"

   _NET_WM_NAME(UTF8_STRING) = "IGEL Setup 11.05.133.01 (Build 6.7.5)"

   WM_NAME(STRING) = "IGEL Setup 11.05.133.01 (Build 6.7.5)"

   WM_NORMAL_HINTS(WM_SIZE_HINTS):

   user specified location: 107, 141

   program specified location: 107, 141

   program specified size: 1398 by 757

   window gravity: NorthWest

   If, however, you get xprop error xprop: error: Can't grab the mouse, then the cursor is occupied by another window such as a popup menu. Free the cursor from that window and try again.

4. Identify the metadata field values for the target application’s window in the displayed list.

   In the example above they are shown in boldface.

   The syntax of the boldfaced WM_Class line is:

   WM_CLASS(string) = "WMAppInstance", "WMClass"

   So in the example line from above,

   WM_CLASS(STRING) = "sun-awt-X11-XFramePeer", "IGEL Setup"

   the value sun-awt-X11-XFramePeer is a WMAppInstance window attribute and IGEL Setup is a WMClass window attribute.

   Similarly, WM_NAME string value IGEL Setup 11.05.133.01 (Build 6.7.5) is a WMName window attribute.

   Note that an app window may not have all three attributes.

5. Make note of the metadata field values and go to the next section, Adding Metadata Field Values to the Admin Console and Rebooting Endpoints.

To add the metadata field values for the application window to the Admin Console:

1. In the Admin Console, select the gear icon and then in the drop-down menu, select ProveID Embedded.

   A ProveID Embedded page opens, showing Lock screen access.

2. Select Add application.

   A Lock screen access: add application page opens.

3. Enter an application name in the Application nickname field.

   This field simply identifies the entry in the lock screen access list.

4. Enter in one or more of the Name, Class, and App instance fields the metadata values you found using either Getting Metadata Field Values for an Application Window from a Log File or Getting Metadata Field Values for an Application Window using the xprop Utility.

   • For the App instance field, enter the WMAppInterface or the WMAppInstance attribute you found, depending on which discovery method you used. Those two slightly different log entry names identify the same attribute.

   • Entering metadata values in two or three fields, rather than in only one field, can help ensure that only the desired application window is allowed atop the lock screen.

   • No error checking occurs for the field values. If you enter an incorrect value, the Admin Console accepts it, but the system does not allow the desired window above the lock screen.

   • If you enable Allow access to all variants of this application, this implements a match to any application window on the endpoint whose Windows metadata fields contain the field values you specify. If you enable this option, be careful to ensure that you do not get undesired windows appearing atop the lock screen. If you don't enable this option, exact matches are required for the field values you specify.

   Click Save.

5. Reboot your ProveID Embedded endpoint to cause the new configuration value to take effect for that endpoint.

6. Test viewing the application window atop the Imprivata ProveID Embedded lock screen on that endpoint:

   • If the application is a native application, trigger the Imprivata ProveID Embedded lock screen and then launch the application using a hotkey or some other method. You cannot launch native apps from the ProveID Embedded agent interface.

   • If your application is virtual, launch the application and then trigger the Imprivata ProveID Embedded lock screen.

   The application should stay atop the lock screen.

   • If it does not, review the metadata field values where you obtained them and in the Lock screen access list in the Admin Console. If needed, obtain fresh metadata field values. Correct any errors in the metadata values in the Admin Console. Then return to step 5.

   • If one or more undesired application windows appear atop the lock screen, deselect checkbox Allow access to all variants of this application if it is checked. Then return to step 5.

7. Reboot all other Imprivata ProveID Embedded clients for which you want the new configuration value to take effect, for example, all Imprivata ProveID Embedded clients at a site or in the enterprise.

8. If you enabled logging of application window activity on one Imprivata ProveID Embedded endpoint in Getting Metadata Field Values for an Application Window from a Log File, disable that logging.

   Reset configuration option log-activity to false in the [windows.monitor] section of the imprivata.conf configuration file on that endpoint.