Installing the EmpowerID Reverse Proxy on Windows

The EmpowerID Reverse Proxy is a server application that sits in front of Web servers, assuming the name and IP addresses of those servers in order to provide authentication and authorization to users requesting the resources (in the form of URIs) provided by those servers. Incoming requests are intercepted by the Reverse Proxy Server and directed to the EmpowerID IdP, where users must authenticate before authorization for the requested resources can be granted.

The EmpowerID Reverse Proxy Server is a server-side JavaScript application managed by Node.js. As such, Node must be installed on the server before the Reverse Proxy Server can be configured for use.

In addition to installing Node, you must also perform the following on a dedicated EmpowerID server:

  • Create a SQL Login on the EmpowerID database for the Reverse Proxy (see prerequisite information)
  • Install the EmpowerID Reverse Proxy.
  • Install Forever. This is a node module used to keep the node server up and running.
  • Create the EmpowerID Proxy Server Windows service. The EmpowerID Reverse Proxy Server Windows service starts and stops the EmpowerID Reverse Proxy Server Node application.
  • Create encrypted password files for the SQL Server Login (and the TLS certificate if you are using SSL)
  • Update config.txt for your environment

SQL Login Prerequisite:

As the Reverse Proxy authenticates users against the EmpowerID database, you need to provide it with a SQL login that has rights to the EmpowerID database. Expand the below drop-down for step-by-step directions on creating the login in SQL Server.

  • Create SQL Login
    1. Open SQL Server Management Studio.
    2. From Object Explorer, create a Login and set the Default database to the instance of the EmpowerID database in your environment. Note that SQL Serve authentication is used.
    3. From the Login Properties dialog, set the User Mapping to EmpowerID Service and public.
    4. To verify the login, open a new instance of the Connect to Server dialog, select SQL Server Authentication and enter the credentials you just created.

To install the EmpowerID Reverse Proxy Server

  1. From your dedicated EmpowerID server, double-click the Reverse Proxy msi you received fro EmpowerID to launch the EmpowerID Proxy Server Setup Wizard.
  2. Click Next to begin the installation.
  3. Accept the terms of the license agreement and click Next.
  4. Select the destination folder and click Next.
  5. Click Install.
  6. Once the wizard finishes the installation, click Finish to exit the wizard.
  7. Next, install Node.

To install Node

  1. From Windows Explorer, navigate to the EmpowerID Proxy Server/Proxy Server/MSIs folder in the EmpowerID installation path.
  2. Double-click the node installer to open the Node.js Setup Wizard.
  3. From the Node.js Setup Wizard, click Next.
  4. Accept the terms of the license agreement and click Next.
  5. Select the installation destination folder and click Next.
  6. Review the features to be installed and click Next.
  7. Click Install.
  8. Once the wizard finishes the installation, click Finish to exit the wizard.
  9. Verify the installation by opening a command prompt and typing node. You should see no errors and be entered in the command line mode of node.js.

To install the Forever Module

  1. Open a command prompt in your normal shell (not the node repl).
  2. From the command line of the command prompt, type the following command. Be sure to include the -g flag as forever needs to be installed globally.
    npm -g install forever

To install the Reverse Proxy Windows Service

  1. From Windows Explorer, navigate to the EmpowerID Proxy Server/Proxy Server/Process folder.
  2. Open the start batch file with any text editor and update the paths to the forever log and index.js file for your environment.
  3. From the process folder, open a command window by typing "cmd" in the folder address bar and pressing ENTER.
  4. From the command prompt, type ""EmpowerID Reverse Proxy Server.exe" install and press ENTER.
  5. In the Set Service Login dialog that appears, type the username for the service login identity in the Username field, the password in the Password and Confirm password fields and then click OK.
  6. Set the identity for the service with the same credentials you set for the other EmpowerID Windows services.

    You should see that the service has been installed.

  7. Open services.msc and verify the installation.

To configure SQL Server for SQL Server Authentication

  1. Open SQL Server Management Studio. 
  2. From Object Explorer, create a Login and set the Default database to the instance of the EmpowerID database in your environment.
  3. From the Login Properties dialog, set the User Mapping to EmpowerID Service and public.
  4. To verify the login, open a new instance of the Connect to Server dialog, select SQL Server Authentication and enter the credentials you just created.

To create password encryption files

  1. From Windows Explorer, navigate to the EmpowerID Proxy Server/Proxy Server folder in the EmpowerID installation path and create a new folder, naming it "passwords."
  2. Navigate back to the Proxy Server folder, open a command window by typing "cmd" in the folder address bar and pressing ENTER.
  3. From the command prompt, type "node encryptPassword password123 passwords\sqlPassword.txt" (without quotes), substituting "password123" with the password of the SQL Login in your environment and "sqlPassword.txt" with the desired name for the password file you are creating.
  4. The following image shows what the command looks like in our environment.

  5. Press the ENTER key.
  6. Node creates the password encryption file and adds it to the specified passwords folder.

To export your SAML certificate

The following export location and certificate name are suggested but not required. You can export the certificate to any desired location and name it as is appropriate for your situation.
  1. From MMC, locate the certificate you are using to sign your SAML assertions. This certificate is used to verify the integrity of the identity assertion issued to the reverse proxy by the EmpowerID identity provider service.
  2. Right-click the certificate and select All Tasks > Export from the context menu.
  3. In the Certificate Export Wizard that appears, click Next.
  4. Select No, do not export the private key and then click Next.
  5. Select Base-64 encoded X.509 (.CER) as the file format and then click Next.
  6. From the Save As dialog that appears, browse to "/Program Files/EmpowerID Proxy Server/Proxy Server/Certs" , type verificationCert in the File name field and then click Save.
  7. Back in the Certificate Export Wizard, click Next and then click Finish.
  8. Repeat the process for the TLS certificate, if used. The TLS certificate should not be a self-signed certificate as it must be trusted by client machines.

Next, add your SQL Connection parameters, TLS and SAML certificate paths, as well as the URL for the EmpowerID IdP service to the EmpowerID Reverse Proxy configuration file. This is done in the config.txt file.

To update config.txt

  1. From Windows Explorer, navigate to the EmpowerID Proxy Server/Proxy Server folder and open the config.txt file with any text editor.
  2. In the config.txt file, locate FILEPATH_PEM_VERIFY_CERT and replace the value with the path to the SAML certificate used in your environment. This certificate is used to verify the integrity of the identity assertion issued by the EmpowerID IdP.
  3. In the config.txt file, locate EID_IDP_URL and replace the value with the URL to the SAML IdP authentication endpoint in your environment. This path should be as follows: https://sso.empoweriam.com/EmpowerIDWebIdPForms/SamlSsoAuthentication, where "sso.empoweriam.com" is the FQDN (or a resolvable alias) of the EmpowerID server hosting the SAML IdP authentication endpoint in your environment.
  4. In the config.txt file, locate SESSION_DURATION_MINUTES and specify the length of time for which you want the cookie issued by the reverse proxy server to remain valid. When a cookie expires, the user to whom the cookie belongs must reauthenticate for further access.
  5. In the config.txt file, locate IP_ADDRESS, HTTP_PORT and HTTPS_PORT and specify the IP address and the ports to which the reverse proxy needs to listen for incoming traffic. If the reverse proxy is the only application listening on the http and https ports, you can leave the IP_ADDRESS value set to 0.0.0.0.
  6. In the config.js file, locate dband replace the userName, passwordEncryptedFilePath, options and server values with those for your environment.
    • DB_UserName - This is the SQL login you created for the reverse proxy application above.
    • DB_PASSWORD_ENCRYPTED_FILE_PATH - This is the path to the encrypted password you created for the SQL login earlier.
    • DB_DATABASE - This is the name of the EmpowerID database in your environment.
    • DB_SERVER - This is the name or IP address of the SQL server in your environment.
  7. Save your changes.