Skip to main content

Epic EPCS VAM Deployment Guide

Updated April 21, 2023

This document details the deployment and configuration of the Epic EPCS Value-Added Module (VAM) on a SecureAuth® Identity Platform (formerly SecureAuth IdP) appliance. The addition of the Epic EPCS VAM in your environment enables authentication and authorization of applications on Epic EPCS.

The SecureAuth Epic EPCS VAM enables seamless integration between the Identity Platform multi-factor authentication (MFA) and the Epic Hyperspace platform for the Electronic Prescriptions of Controlled Substances (EPCS) system. Using this integrated package, qualified physicians can write prescriptions quickly and securely while meeting DEA requirements for electronic prescriptions.

This guide also includes instructions on installing and configuring the VAM that enables the link between Epic Hyperspace and the Identity Platform.

What's new in version 3.1

The Value-Added Module (VAM) by SecureAuth for Epic ECPS in version 3.1 supports selection of MFA options for authentication, including biometric options. As part of the login workflow, the user interface shows all the available MFA options to choose from.

Why select the SecureAuth Identity Platform?

SecureAuth’s flexible authentication framework allows providers to deploy DEA compliant two-factor authentication (2FA) in ways that are not intrusive on physicians; in many cases SecureAuth can actually optimize workflows by reducing clicks. Its aim is to provide the quickest way to ensure that the accessing physician is the one authorized to approve the prescription, per DEA standards.


  • Seamless integration into preexisting Epic e-Prescribing workflows

  • Multiple authentication methods that not only meet DEA regulations but also make 2FA easy for physicians – such as push-to-accept, fingerprint, and other DEA-compliant methods

  • Flexible authentication platform that allows providers to select the 2FA method which best meets their needs

Benefits and use cases

The Epic EPCS VAM enables SecureAuth MFA and modern authentication methods for stronger security.

MFA and adaptive authentication

MFA methods used for EPCS transactions are required to meet FIPS 140-2 Level 1. Choose among the following available authentication methods.

  • SecureAuth Mobile <Push-To-Accept>

  • SecureAuth Mobile App <Soft Token> TOTP

  • SecureAuth <Hardware> Token TOTP

  • SecureAuth Mobile Fingerprint

  • SecureAuth Mobile FaceID


Verify that these methods meet your organization’s interpretation of the EPCS Guidelines.

List of MFA options

The following example illustrates a newly added workflow presenting the list of all FIPS 140-2 compliance MFA methods for the user to choose from. To activate this new workflow we have to update ShowMFA="1" in SASettings.xml, or else it works as before in version 2.0.

In this example:

  1. The physician enters a username and is prompted for a method to receive the required password; if RequirePassword key is set to 1 in SASettings.xml, or else it skips to step 3 in the login workflow.

  2. The physician enters the password and presses Enter.

  3. This opens a user interface with list of available MFA options.

  4. The physician needs to select a preferred MFA option and presses Enter.

  5. Based on the selected MFA option, the next page appears to complete 2FA.

  6. The physician receives entry to the EPCS system.


Reading a fingerprint/FaceID is compliant with the FIPS 140-2 standard and can only be handled by those mobile devices that support fingerprint/FaceID reading.

  • Fingerprint/FaceID: When a physician selects fingerprint or face ID, they will receive a fingerprint/faceID request on their mobile device.

  • Send Login Request (Push to Accept): When a physician selects send login request, they will receive a login request on their mobile device.

  • Send passcode to mobile app: When a physician selects send passcode to mobile app, they will have to enter a passcode sent to mobile app in the next screen and press Enter.

  • Time-based passcode (TOTP): When a physician selects time-based passcode, they will have to enter a time-based passcode in the next screen and press Enter.

  • Personal Identification Number (PIN): When a physician selects personal identification number (PIN), they will have to enter their PIN in the next screen and click Enter.


Soft-token EPCS with second factor

The following example illustrates a commonly deployed 2FA method using mobile devices featuring FIPS 140-2-compliant one-time passcode (OTP) tokens. This method is easy for physicians to use, and because of its FIPS 140-2 compliance, it meets the DEA’s requirement for 2FA.

In this example:

  1. The physician enters a user name and is prompted for a method to receive the required passcode.

    The physician receives the passcode on their registered device.

  2. The physician enters the received passcode and presses Enter.

  3. The physician is granted access to the EPCS system.


Soft-token EPCS with password

In a variation on the first example, the process requires the physician to perform soft-token EPCS second factor as shown in the following illustration examples (using both a password and a passcode).

The physician uses their mobile application with fingerprint ID (if supported by FIPS 140-2) to unlock their onetime passcode.

  1. The physician enters a user name and is prompted for a fingerprint.

  2. The physician authenticates with a fingerprint on the mobile device.


Reading a fingerprint is compliant with the FIPS 140-2 standard and works only on mobile devices that support fingerprint reading.


The physician is granted access to EPCS data.

Push-to-Accept EPCS

To comply with DEA requirements while providing the quickest possible access, the Identity Platform also features push-to-accept with TouchID for EPCS authentication. Many providers are moving to push-to-accept with TouchID because it not only reduces the number of clicks and character entries a physician must perform, but also incorporates all three of the authentication factors identified by the DEA:

  • Something you know (username/password).

  • Something you have (mobile device).

  • Something you are (fingerprint for TouchID).

An example of the process required to perform push-to-accept EPCS 2FA is shown in the following illustration example:

  1. The physician opens the application on their mobile device or computer.

  2. The application prompts the physician for authentication. At the same time, the secondary device is activated.

  3. The physician pushes a button on the secondary device to accept the request for entry.

  4. The application then allows physician access to the required data.



If Push-to-Accept is used with accounts that have multiple registered mobile devices, a page appears with a list of mobile devices from which the user can select, as shown below.


The process flow using the Epic EPCS VAM is shown below.


Configuration tasks to support this VAM

This section covers the required configurations to integrate this VAM with the Identity Platform.


This document is based on the development of the Epic EPCS VAM using the following systems:

  • Epic EPCS version 8.4 and 8.7 installed and running on Windows

  • Identity Platform version 9.2 or later

Internal developer tested environments

SecureAuth VAM team developed a test tool for testing and validating the result internally, EPIC Hyperspace was not available internally.

Configure the Identity Platform

Configuring the Identity Platform for use with Epic EPCS involves the creation of a realm dedicated to handling the necessary API instructions.


Configuring the Identity Platform for use with Epic EPCS should be handled, at least initially, by the SecureAuth deployment staff and should not be the client’s responsibility.

  1. Designate a realm in your Identity Platform appliance to provide API access to the SecureAuth Epic EPCS VAM.

    For more information about creating a new realm, see SecureAuth IdP Realm Guide.

  2. Go to the Data tab and configure the required fields for a data store integration.

    A data store integration is required for the Identity Platform to pull user profile information during the login process. For more information about configuring the Data tab, see Data Tab Configuration.

  3. Select the API tab.

  4. In the API Key section do the following:

    1. Select the Enable API Key for this realm check box.

    2. Click Generate Credentials to create a new Application ID and Application Key, which are unique to this realm.



      The API key looks as if it consists of 64 random characters, but it is actually composed of 32 two-character hexadecimal values. This is important when using the API key to produce the required HMAC hash.

    3. Copy and paste each of the credentials into a text editor.

      These values will be required in the HTTP Header configuration.

  5. In the API Permissions section, do the following:

    1. Select the Enable Authentication API check box.

  6. Save your changes.

Install and configure the Epic EPCS VAM

  1. Copy the provided ZIP file to a location on the system running Hyperspace.

  2. Do one of the following:

    • If running the Hyperspace thick client from a workstation, install the SALoginDevice on the workstation itself, for example Win10.

    • If using a VDI server, such as Citrix, for access to Hyperspace, install the SALoginDevice on all Citrix servers.

  3. Extract the SecureAuth folder to the C:\ drive. This folder can be installed in another location if write access is provided to the logs folder.

  4. Open the SecureAuth folder and run RegisterSALoginDevice.bat as an Administrator.

    UnRegister - C:\Windows\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe
    "C:\Epic EPCS Login Device\SecureAuthLoginDevice.dll" /u
    Register - C:\Windows\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe
    "C:\Epic EPCS Login Device\SecureAuthLoginDevice.dll" /codebase

    This adds SecureAuthLoginDevice.dll to the system code base.


    By executing this .bat file, the SecureAuth Epic EPCS VAM is automatically registered, enabling you to bypass regsvr32 for this DLL.

  5. Open SASettings.xml using a text editor and modify the following settings:




    Default is “Hyperspace”, if appsetting is missing or empty then it will consider as a "Hyperspace". Set value to “Hyperdrive”, If need to use for Hyperdrive.


    The URL used to access the Authentication API realm defined in the SecureAuth configuration.

    It must be accessible by HTTPS and the certificate used to serve the SSL connection must be trusted by the Epic Hyperspace server.


    Deprecated, should be empty.


    The Application ID provided in the Identity Platform appliance configuration for the Authentication API.


    The Application Key provided in the Identity Platform appliance configuration for the Authentication API.


    Indicates the number of failed attempts by the user to enter a correct OTP before the Epic EPCS VAM returns to Epic and fails to authenticate the message.


    Default value set to 0, which turns off logging.

    Do not change this value unless instructed to do so by a SecureAuth Engineer.


    Indicates the title text that displays on the Epic EPCS VAM dialog box.


    When set to 1, the user is required to enter their password for the configured data store in the Authentication API realm when using the Epic EPCS VAM.


    Specifies the full file path on the appliance for the custom logo image displayed in the Epic EPCS VAM. For example, C:\SecureAuth\logo.png.


    Enables Push-to-Accept as the second factor method provided by the Epic EPCS VAM. Valid values:

    • 0 – Default value, which disables push-to-accept.

    • 1– Enables this setting. The following scenarios can occur:

      • When the Push-to-Accept method is used with accounts that have multiple registered mobile devices, the software displays a list of devices from which the user can select.

      • When no devices are found, the software notifies the user

      • When only one device is found, it automatically sends the push request without waiting for a selection.


    Enables or disables the static PIN feature. Valid values:

    • 0 – Indicates the use of TOTP (OATH) token

    • 1 – Enables the use of a static PIN. When this feature is enabled, it verifies against the static PIN. When no PIN is found for the user, it defaults to using a standard TOTP token.


    Skip Oath/TOTP/PUSH authentication for non-mobile devices:

    • 0 – Enable authentications for all devices.

    • 1 – Disable authentication for Windows/Mac devices. That’s means authentication will be skipped for Windows/Mac devices.


    Indicate whether to show the MFA workflow to users. Valid values:

    • 0 – Disable the MFA workflow

    • 1 – Enable the MFA workflow


    This is a comma separated MFA option value to decide the order of MFA options shown on the user interface.

    The default order is PUSH,TOTP,PIN.


    Specify the file path for the custom logo image displayed for biometric options list.

    For example: C:\SecureAuth\ bioLogo.png


    Specify the file path for the custom logo image displayed for PIN options list.

    For example: C:\SecureAuth\ pinLogo.png


    Error message to show to user when there is no MFA option available.


    Error message to display to user when no MFA option selected.


    Text to display once user selects biometric/push request option.


    Text to display if there is an error while validating the input.


    Text to display if biometric/push request is denied.


    Text to display if biometric/push request has failed.


    Text to display if biometric/push request is not found.


    Text to display if biometric/push request is invalid.


    Text to display if there is some unknown error.


    Text prompting user to provide passcode.


    Text prompting user to provide TOTP.


    Text prompting user to provide PIN.


    Text prompting user to select another authentication method (in case of current selection option is not working for any reason).


    Text to display when the passcode the user provides does not match.


    Text to display when there is an issue with the selected device.


    Text to display when the TOTP the user provides does not match.


    Text to display when the user provides a blank passcode.


    Text to display when the user provides a blank TOTP.


    Text to display when the user provides a blank PIN.

  6. Refer to the following sample of the SASettings.xml file.

    <?xml version="1.0" encoding="utf-8" ?>
    	<sASetting EPICVersion="Hyperspace" />
    	<sASetting WindowTitle="SecureAuth EPIC Login" />
    	<sASetting SecureAuthAPIUrl="https://<domain>/SecureAuthXX" />
    	<sASetting EPCSUrl="" />
    	<sASetting AppID="xxxxxxxxxxxxxx" />
    	<sASetting AppKey="xxxxxxxxxxxxxxxxxxxxxxxxxxxx" />
    	<sASetting Retry="3" />
    	<sASetting LogLevel="2" />
    	<sASetting EnablePush="1" />
    	<sASetting LogoPath="logo.png" />
    	<sASetting RequirePassword="0" />
    	<sASetting PreferStaticPin="1" />
    	<sASetting PreventNonMobileDevices="0" />
    	<sASetting ShowMFA="1" />
    	<sASetting MFAOrder="PUSH,TOTP,PIN" />
    	<sASetting BioLogoPath="bioLogo.png" />
    	<sASetting PinLogoPath="pinLogo.png" />
    	<sASetting NoMFAError="Please select one of the available MFA method." />
    	<sASetting NoMFASelected="Please select a MFA." />
    	<sASetting AcceptDenyPushRequest="Please Accept/Deny the push request sent to your device" />
    	<sASetting APIConnectionError="Unable to validate or send {reqType} push request." />
    	<sASetting APIDeniedError="Push Request Denied." />
    	<sASetting APIFailedError="Push Request Failed." />
    	<sASetting APINotFoundError="Push Request Not Found." />
    	<sASetting APIInvalidError="Push Request Invalid." />
    	<sASetting APIUnknownError="Push Request Unknown Error." />
    	<sASetting EnterPasscode="Enter Passcode sent to your device." />
    	<sASetting EnterTOTP="Enter the code from your SecureAuth OTP Mobile App." />
    	<sASetting EnterPIN="Enter your registration PIN." />
    	<sASetting UnknownMFAError="Some error occurs! Please select another MFA method." />
    	<sASetting PasscodeNotMatchError="Provided passcode does not match." />
    	<sASetting SelectedDeviceError="Selected device is not a mobile device. Please contact to administrator." />
    	<sASetting TOTPNotMatchError="Provided TOTP does not match." />
    	<sASetting BlankPasscode="Please enter the passcode sent to your device." />
    	<sASetting BlankTOTP="Please enter the code from your SecureAuth OTP Mobile App." />
    	<sASetting BlankPIN=" Please enter your registration PIN." />
  7. Save the SASettings.xml file.

Create the SecureAuth login device

  1. In Chronicles, access the Authentication Devices (E0G) master file, then go to <Data Management> 1. Enter Data | Create/Edit Device <Y>.

  2. Enter a name for the device. For example, SecureAuthLoginDevice.

  3. Enter a new ID. For example, 10001+.

  4. On the General Settingspage, set the following:

    • Set the Description to SecureAuthLoginDevice.

    • Set the Platform to 1-Desktop.

  5. On the Desktop Settings page in the ProgID field, enter SecureAuthLoginDevice.Receiver2 supporting both Hyperdrive and Hyperspace which is for EPIC VAM version 3.1+.


Older EPIC VAM version supporting Hyperspace ONLY using SecureAuthLoginDevice.Reciever.

Configure the SecureAuthLoginDevice as the secondary authentication device

Once the SecureAuthLoginDevice is created, you will need to specify it as the secondary authentication device.

  1. Open Hyperspace and go to Epic | Admin | Access Management | Authentication Administration.

  2. Select the System level.

  3. Select the desired Context.

  4. Set the first authentication method as the Primary Device.

    Typically, this is the username and password.

  5. Set the SecureAuthLoginDevice as the Secondary Device.

  6. Click Accept.

Test the Epic EPCS VAM

Epic provides a standalone .NET Testing tool that can be used to verify that the Epic EPCS VAM is working before adding it to the Hyperspace configuration. The steps below outline how to use the tool.

  1. From the SecureAuth folder, open the Test folder.

  2. Run the StandAloneNETTester.exe file.

    The MainForm window appears.

  3. In the ProgID field, enter SecureAuthLoginDevice.Receiver2.

  4. Click Authenticate.

    The RequestForm window appears.

  5. Do the following:

    1. In the Key field, enter the UserID.

    2. In the Value field, enter the username to be tested.

  6. Click Add Data.

  7. Click Return True.

  8. Follow the authentication flow as prompted on the screen.

    After successful authentication, you will see the following screen.


The Epic EPCS VAM appears. If the device completes successfully, the Results field on the MainForm window updates with a success; otherwise, the field displays Perform Action Failed.

Hyperdrive configuration

  1. Deploy “SecureAuth.EPIC.dll” from the package received under “D:\SecureAuth\SecureAuthXX\bin” of the SecureAuth API realm.

  2. Setup SAML IDP-initiated post auth realm as per below configuration.

  3. Set the Name ID Format to urn:oasis:names:tc:SAML:1.1:nameidformat:unspecified.

  4. Send SAML issuer and signing certificate from SecureAuth IdP to EPIC.

    Download the certificate and make a note of the SAML Issuer as shown in the highlighted screenshot above.

  5. Export the entire SecureAuth certificate chain and key to a .PFX file.

  6. Export the entire certificate chain to a .PEM file using the following command:

    openssl pkcs12 -in -nokeys -out SecureAuth.SAML.wse3.pem

    The .pem file must be placed on each operational database server or user application server (if ECP).


    Epic recommends using the /epic/pki/cert directory as the location for the .PEM cert file, since this is where the other certificates are stored.

    This command exports the ROOT CA, ICA cert, and server cert.

    The CN value will change based on the certificate each customer will use. For example:


    • CN=SecureAuth G3 Root Certificate Authority

    • CN=SecureAuth G3 Intermediate Certificate Authority 2A

  7. In the Authentication Devices (E0G) master file, add the SAML Issuer (SecureAuth realm).

  8. Enter the SAML Key File, which is the path to the location of the .PEM cert.

    See the following example.

  9. In the SASettings.xml file, update "<sASetting EPICVersion="Hyperspace" />" to " <sASetting EPICVersion="Hyperdrive" />".

  10. Now when you test using the test tool and if authentication is successful, then you will see a SAML response in the text area.

    See the following screen shot as an example.


Test Epic EPCS VAM using Hyperdrive

EPIC Hyperdrive testing is ONLY successful if EPIC has properly configured Hyperdrive for your organization and per SAML configuration from SecureAuth as noted in this document. Work with the EPIC team to make sure Hyperdrive environment is ready for testing.

See the upgrade information below for any issues with deployment and testing.

Upgrade information

Before upgrading SecureAuth software, open a Support ticket. The process of upgrading to a newer SecureAuth software version might cause the SecureAuth VAM to become invalid and stop working. When your site is ready to upgrade SecureAuth software, get started by creating a support ticket selecting I have a question or issue regarding SecureAuth Value-Added Modules (VAMs) from the "Submit a request" list. A SecureAuth Tailoring engineer will contact you to evaluate and ensure that the VAM will work with updated SecureAuth software.