Contents x
    Installation
    • 21 Sep 2023
    • 7 Minutes to read
    • Contributors
    • Dark
      Light
    • PDF
    Contents

    Installation

    • Updated on 21 Sep 2023
    • 7 Minutes to read
    • Contributors
    • Dark
      Light
    • PDF
    Article summary

    (Installation File Name is Identity Automation ProxCard Epic Login Device version 3.x)

    This section covers the various installation requirements and steps for the following architecture pieces of the Epic Authentication Plug-in.

    Environment

    Epic Hyperspace

    CitrixServer

    Endpoint

    Environment

    Prerequisite Installs:

    • HealthCast® ExactAccess® or HealthCast® ProxAuth Server
    • Epic® Hyperspace®
    • Citrix® Target Platform

    Note: Please see the Citrix Server and Endpoint Install section for specific details.

    Epic Hyperspace

    Prerequisite Configuration

    • Configure a Primary Authentication Device (Required)
    • Configure a Passive Authentication Device for Narrator Support (Optional)

    Note: Click the above links to be directed to installation instructions.

    Citrix Server

    Prerequisite Installs / Configurations:

    • .NET 4.6.1
    • To support a Citrix Storefront Configuration:
      • HTTP Basic Authentication method is enabled on the Storefront server
      • Epic Hyperspace published using Citrix Access management or Delivery Services Console
    • To support an Epic Warp Drive Configuration:
      • Follow Epic’s recommendations

    Citrix Server Authentication Plugin Install

    1. There are two methods to configure the Primary Authentication Device installation.
      Note: It is necessary to run the following installations using elevated permissions.
      1. Use MSI properties passed into the install by command line at installation; or
      2. Update registry settings after installation. Based on your configuration, look through the properties and determine if the defaults will work or if you need to modify these for your configuration.
    2. EPIC 2018 and higher install settings:
      1. Example: Hyperspace 2018, %systemroot%\system32\msiexec/i "HealthCast ProxCard Epic Login Device.msi"
      2. Optional setting: set TFA_USEREMOTE to True if the ExactAccess Client is installed on the Citrix Server and you want the plugin to connect to the endpoint.
        Note: This will also support interacting with a local instance of XA if running a published desktop or published XAUCM with a publish instance of Hyperspace.
      3. An optional setting: after installation, LoginDeviceBackgroundImage is used to customize the background image of the primary authentication screen background image. By default, this setting is not added. After the installation, the following registry setting can be added with the path and filename of the background image file to change the background image:
        [HKEY_LOCAL_MACHINE\SOFTWARE\HealthCast\ExactAccess\TFA Settings]"LoginDeviceBackgroundImage"="C:\\MyImageFiles\\login-background.png"
      4. The file and location will need to be accessible by all windows users running Hyperspace. The file also needs to be in a PNG or JPG file format and sized 560 x 574 (width x height pixels).
      5. An optional setting, after installation, InitialLoginMessage is used to customize the message text on the initial login form displayed. The default text is “tap your badge”.
        [HKEY_LOCAL_MACHINE\SOFTWARE\HealthCast\ExactAccess\TFA Settings]" InitialLoginMessage"="my login message".
      6. Non-Authentication Device configuration is not supported for 2018.
    3. To upgrade a Citrix Server from 2.3.x or 3.x to support 2017 and 2018 on the same Citrix server, apply the MSI properties required for 2017, see the examples listed above.
    4. To use Logoff Cleanup from the Published Hyperspace session running on the Citrix server, perform the following configurations and setting updates.
      1. To use Logoff Cleanup, the settings in the xaLogoffCleanup.xml file in the plugin install folder on the Citrix server will need to be updated. See Logoff Cleanup documentation.
      2. In addition, there are three settings to consider configuring on the Citrix Server:
        1. TFA_LOGOFFCLEANUP_ONLOCK
          • Use this setting to set Logoff Cleanup to be called on XA lock and if "DisableOnBeforeLock" is set to "True".  Using these two settings will allow Logoff Cleanup to be called without securing or logging off Hyperspace.
        2. TFA_LOGOFFCLEANUP_SEC
          • Use this setting to set Logoff Cleanup to be called on Hyperspace secure.
        3. TFA_LOGOFFCLEANUP
          • Use this setting to set Logoff Cleanup to be called on Hyperspace logoff.

    EPIC 2017/2015 Install settings:

    TFA_ACTIVECONNECTOR

    TFA_AIE

    TFA_EDMANAGERENABLED

    Examples (Primary Authentication Device Configured):

    Hyperspace 2017

    %systemroot%\system32\msiexec /i "HealthCast ProxCard Epic
    Login Device.msi" TFA_ACTIVECONNECTOR=
    "HCIE83Connect.cls83E2016" TFA_AIE=0
    TFA_EDMANAGERENABLED=False

    Hyperspace 2015

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi"
    TFA_ACTIVECONNECTOR="HCIE82Connect.cls82E2015" TFA_AIE=0
    TFA_EDMANAGERENABLED=False

    Examples (Warp Drive with Primary Authentication Device Configured):

    Hyperspace 2017

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi"
    TFA_ACTIVECONNECTOR="HCIE83Connect.cls83E2016"
    TFA_AIE=1 TFA_EDMANAGERENABLED=False

    Hyperspace 2015

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi"
    TFA_ACTIVECONNECTOR="HCIE82Connect.cls82E2015"
    TFA_AIE=1 TFA_EDMANAGERENABLED=False

    Examples (Primary Authentication Device NOT Configured):

    Hyperspace 2017

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi"
    TFA_ACTIVECONNECTOR="HCIE83Connect.cls83E2016"
    TFA_AIE=1 TFA_EDMANAGERENABLED=True

    Hyperspace 2015

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi"
    TFA_ACTIVECONNECTOR="HCIE82Connect.cls82E2015"
    TFA_AIE=1 TFA_EDMANAGERENABLED=True

    Optional Setting for Endpoint Connection

    Set TFA_USEREMOTE  to True if the ExactAccess Client is installed on the Citrix Server and ensure the plugin connects to the endpoint.

    Endpoint

    Note: It is necessary to run the following installations using elevated permissions.

    Prerequisite Installs

    • NET 4.6.1
    • Citrix client configured for environment providing Epic Hyperspace
    • HealthCast ExactAccess client installed and configured for the environment
    • Epic Hyperspace has been configured to load the Primary Authentication Device, see How to Configure Primary Authentication Device in Epic.

    Installation

    1. There are two methods to configure the Primary Authentication Device installation:
      1. Use MSI properties passed into the install by command line at installation; or
      2. Update registry settings after installation. Based on your configuration, look through the properties and determine if the defaults will work or if you need to modify these for your configuration.
    2. Depending on which Hyperspace configuration is used, go to that section for installing.
      1. Storefront is used to launch Hyperspace
      2. Warp Drive is used to launch Hyperspace
      3. Hyperspace is started from a locally installed instance

    Storefront is used to launch Hyperspace

    1. The following settings are required to configure pubLauncherSF.exe to launch Hyperspace published via Storefront:
      • TFA_HYPERSPACE_WINDOW_TITLE
      • %systemroot%\system32\msiexec /i "HealthCast ProxCard Epic Login Device.msi"
      •  TFA_SF_URL=https://servername/citrix/web
      •  TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace
        -" TFA_LAUNCHTYPE=4
      •  TFA_SF_Resource_Name=PublishedAppName
      •  TFA_SF_AUTHTYPE=2
    2. To determine additional pubLauncherSF settings for the Citrix environment, run the following command as an administrator to start up the configuration GUI:
      1. "C:\Program Files (x86)\HealthCast\ExactAccess\pubLauncherSF.exe" /config
      2. After the "pubLauncherSF Configuration" window is displayed, select "HyperspaceConfiguration1" in the "Configuration" dropdown list.
      3. Use the following graphic to determine the additional MSI properties or registry settings you need to modify:

    Warp Drive is used to launch Hyperspace

    1. First, verify that Warp Drive is configured to use a generic Windows account to interact with Citrix. This can be verified using the Warp Drive Admin tool.
      1. In Warp Drive Admin, in the “Persistent/Credentials” Tab, check that the “Always use generic Windows account” is checked.
      2. Warp Drive Admin can be found here on an endpoint where Warp Drive is installed:
        • 2018: "C:\Program Files (x86)\Epic\v8.4\Shared Files\EpicEWarpDriveAdmin84.exe"
        • 2017: “C:\Program Files (x86)\Epic\v8.3\Shared Files\EpicEWarpDriveAdmin83.exe"
        • 2015: "C:\Program Files (x86)\Epic\v8.2\Shared Files\EpicEWarpDriveAdmin82.exe"
    2. Use the following settings to use Warp Drive directly to launch Hyperspace:
      1. If you are reluctant to update the endpoint or if the integrated connector is not working as expected, use the following properties to configure warp drive settings:
      2. TFA_LAUNCHTYPE
      3. TFA_HYPERSPACE_WINDOW_TITLE
      4. TFA_AUTOLAUNCH
        Example Command Line: %systemroot%\system32\msiexec /i "HealthCast ProxCard Epic Login Device.msi" TFA_LAUNCHTYPE=2 TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace -" TFA_AUTOLAUNCH="False”
      5. After installing the plugin, configure Warp Drive to be launched on Windows startup. If necessary, follow Epic recommendations for other Warp Drive settings. In addition, configure Warp Drive to be started using autostart=true and the alwayshide=true command line settings.
    Note:
    Make sure that the TFA_LAUNCHTYPE MSI property is set to 2 when installing. If the property is not set, the installation will register the plug-in on the endpoint, breaking EpicDICAWrapperxx.exe, keeping Hyperspace from loading our plugin, or causing it to close.
    • If the MSI property is not set at install, the endpoint can be fixed by removing the following registry key: HKEY_CLASSES_ROOT\HCILoginDeviceNET.ProxCard
    Optional Settings for an integrated connector to launch Warp Drive:

    Optionally, you can use the following settings to use our integrated connector to launch Warp Drive:

    • TFA_LAUNCHTYPE
    • TFA_HYPERSPACE_WINDOW_TITLE
    • TFA_WARPDRIVE_CONNECTOR
    Example Command Line (Hyperspace 2018+):

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi" TFA_LAUNCHTYPE=2
    TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace -"
    TFA_WARPDRIVE_CONNECTOR="Epic2018\HCI.WarpDriveLauncher.exe"

    Example Command Line (Hyperspace 2017):

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi"
    TFA_LAUNCHTYPE=2 TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace -"
    TFA_WARPDRIVE_CONNECTOR="hciwd83.exe"

    Example Command Line (Hyperspace 2015):

    %systemroot%\system32\msiexec /i
    "HealthCast ProxCard Epic Login Device.msi"
    TFA_LAUNCHTYPE=2 TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace -"
    TFA_WARPDRIVE_CONNECTOR="hciwd82.exe"

    Hyperspace is started from a locally installed instance

    1. Use the following to configure the Primary Authentication Device to use a locally installed instance of Hyperspace. This configuration would be used for VDI configurations where Hyperspace is installed on the VDI desktop.
    2. For 2018 Hyperspace implementations use the following command line settings:
      1. TFA_LAUNCHTYPE
      2. TFA_HYPERSPACE_PATH
      3. TFA_HYPERSPACE_PARAMS
      4. TFA_HYPERSPACE_WINDOW_TITLE
        • Example Command Line (Hyperspace 2018):
        • %systemroot%\system32\msiexec
          /i "HealthCast ProxCard Epic Login Device.msi" TFA_LAUNCHTYPE=1
          TFA_HYPERSPACE_PATH= "C:\Program Files
          (x86)\Epic\v8.4\Shared Files\EpicD84.exe"
          TFA_HYPERSPACE_PARAMS=" EDAppServers84.EpicApp Name=Desktop84 env=PRD"
          TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace -"
    Command line settings for 2015 and 2017 Hyperspace implementations:
    • TFA_ACTIVECONNECTOR
    • TFA_LAUNCHTYPE
    • TFA_HYPERSPACE_PATH
    • TFA_HYPERSPACE_PARAMS
    • TFA_NOCLOSE
    • TFA_HYPERSPACE_WINDOW_TITLE

    Example Command Line (Hyperspace 2017)

    %systemroot%\system32\msiexec
    /i "HealthCast ProxCard Epic Login Device.msi"
    TFA_ACTIVECONNECTOR="HCIE83Connect.cls83E2016"
    TFA_HYPERSPACE_SECURE=True TFA_LAUNCHTYPE=1 TFA_HYPERSPACE_PATH=
    "C:\Program Files (x86)\Epic\v8.3\Shared Files\EpicD83.exe"
    TFA_HYPERSPACE_PARAMS=" EDAppServers83.EpicApp Name=Desktop83
    env=PRD" TFA_NOCLOSE=True TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace
    -"

    Example Command Line (Hyperspace 2015)

    %systemroot%\system32\msiexec
    /i "HealthCast ProxCard Epic Login Device.msi"
    TFA_ACTIVECONNECTOR="HCIE82Connect.cls82E2015"
    TFA_HYPERSPACE_SECURE=True TFA_LAUNCHTYPE=1 TFA_HYPERSPACE_PATH=
    "C:\Program Files (x86)\Epic\v8.2\Shared Files\EpicD82.exe"
    TFA_HYPERSPACE_PARAMS=" EDAppServers82.EpicApp Name=Desktop82
    env=PRD" TFA_NOCLOSE=True TFA_HYPERSPACE_WINDOW_TITLE="Hyperspace
    -"

    Additional Settings to Consider for all Endpoint Configurations:

    Below is a list of settings to aid in the endpoint configuration. For more information about each individual setting, see MSI Properties and Registry Settings.

    1. Hyperspace workflow
      1. Secure Hyperspace when locking (tap-out) the ExactAccess client.
        • TFA_HYPERSPACE_SECURE
      2. Logoff Hyperspace when locking (tap-out) the ExactAccess client.
        • TFA_HYPERSPACE_SECURE
      3. Logoff or lock the ExactAccess client when a user secures or logs off Hyperspace.
        • TFA_LOGOFF_XA_ON_EPIC_SECURE_LOGOUT
      4. Set Hyperspace to not be secured or logged out on ExactAccess client lock.
        • TFA_DISABLE_ONBEFORELOCK
      5. Set Hyperspace to not be secured or logged out on ExactAccess client lock if triggered by inactivity timeout.
        • TFA_ENABLE_ONBEFORELOCKTIMEOUT
      6. Start Hyperspace at user login and unlock.
        • TFA_AUTOLAUNCH
      7. Start Hyperspace at user log out or lock.
        • TFA_AUTORESTART
        • TFA_AUTORESTARTDELAY
      8. Configure to use ExactAccess stored credentials to support Community Connect configurations.
        • TFA_EPICUSERCIID
        • TFA_EPICUSERCIID_CAPTION
        • TFA_EPICUSERCIID_PROMPT
    2. ExactAccess client configuration.
      1. Non-locking Kiosk mode
        • TFA_ENABLE_ONBEFOREQUITUSER
    3. Secondary authentication, cosign, or re-authentication.
      1. TFA_UITIMEOUTSECONDS

    Settings and Considerations for Epic 2018 and Newer

    1. When installed with Epic 2018 and newer, the new plugin always has logged on by default and will log to the "C:\temp\logs" folder by default. This can be changed by editing the "log4net.config" file in the "C:\Program Files (x86)\HealthCast\HCILoginDevice\Epic2018" folder with notepad.
    2. It is currently configured to create log files per user connection and will log it in the format of:
    3. ${CLIENTNAME}_${USERNAME}_log.txt
    4. The log files roll over to a max of 10. Each log file will only grow to 100k creating a max log file size for each user of 1Meg total.
    5. The location in which log files are saved can be changed by editing the value in the following line:
    <file
type="log4net.Util.PatternString"
value="C:\Temp\Logs\${CLIENTNAME}_${USERNAME}_log.txt" />

    Note: It can be changed to log to a UNC path, however, all users will need the following permissions:

    • Read Attributes
    • Write
    • Delete

    The number of roll backup files can be changed by editing the value in the following line:

    <maxSizeRollBackups value="10" />

    The file size of each file can be changed by editing the value in the following line:

     

     <maximumFileSize value="100KB" />

    The logging can be turned off by setting the value in the following line to "OFF"

    <level value="DEBUG" />

    Debug Logging Epic 2017/2015

    To enable logging, add the following registry setting on the endpoint workstation registry.

    Note: Only the Hyperspace instance connected running from or on the endpoint workstation with this setting will create log files.

    [HKEY_LOCAL_MACHINE\SOFTWARE\HealthCast\ExactAccess\TFA Settings]
    "EnableDebug"=dword:00000001

    This setting will be recognized by the following components running on the Citrix server:

    • hciepicsessionmgr.exe
    • HCILoginDevice.dll
    • HCITFAUI.dll
    • xaRemoteNotify.exe

    They will log to the following folders and files on the Citrix server:

    • %APPDATA%\HealthCast\hciepicsessionmgr\hciepicsessionmgr.log
    • %APPDATA%\HealthCast\HCILoginDevice\HCILoginDevice.log
    • %APPDATA%\HealthCast\HCITFAUI\HCITFAUI.log
    • %APPDATA%\HealthCast\xaRemoteNotify\xaRemoteNotify.log
    Was this article helpful?
    What's Next