Installing as a Windows service

The Helix Authentication Service can be deployed to Windows-based systems, and managed as a Windows service. The guide below outlines the installation and configuration process.

Installation

Prerequisites

Download and run the Windows-based installers for Git and Node.js LTS. Note that the native tool chain, available with the Chocolatey package manager, is not required for the authentication service.

Installing Module Dependencies

Installing the module dependencies for the authentication service is done from a command prompt. Open a Windows PowerShell window (preferably as an Administrator) and change to the directory containing the authentication service, then run the following commands:

> npm ci --only=prod --no-optional
> npm -g install node-windows
> npm link node-windows
> node .\bin\install-windows-service.js

If you run the commands as a normal user, as opposed to an administrator, several User Access Control prompts from Windows will request your permission for the installation of the service.

HAS is now installed and running as a Windows service. If the system restarts, the authentication service starts automatically.

Starting and Stopping the Service

You can start and stop the HAS Windows service by using the Windows service utilities. The Services application provides a graphical interface for this purpose.

Alternatively, the NET command can be run as administrator from the command shell:

To stop the service,

> net stop helixauthentication.exe

To start the service,

> net start helixauthentication.exe

Configuration

The configuration of the authentication service is managed through environment variables. An easy method for setting the variables for the service is with a file named .env in the directory containing the authentication service. The .env file is a text file that contains names and values, separated by an equals (=) sign. For example:

1. Stop the service.

2. Add these lines to the .env file:

   SVC_BASE_URI=https://has.example.com
LOGGING='C:\\helix-auth-svc\\logging.config.js'

3. Start the service.

For additional settings, see Configuring Helix Authentication Service.

Logging

The output of the authentication service is captured in text files in the bin\daemon directory within the directory containing the authentication service. The error output is in a file named helixauthentication.err.log and the normal output is in a file named helixauthentication.out.log.

By default, basic logging of the service executable is written to the Windows event log in a source named helixauthentication.exe, which shows when the service starts, stops, or has critical errors. There might also be a second source named Helix Authentication wrapper that is created by the program that runs the authentication service as a Windows service.

The authentication service supports writing its own logging to the events log, and this can be enabled by configuring the logging. See the Logging section. To enable logging to the Windows event log, use the transport value of event, and optionally define additional properties, as described below.

Name	Description	Default
eventLog	Selects the event log scope, either APPLICATION or SYSTEM	APPLICATION
source	Label used as the source of the logging event	HelixAuthentication

An example of logging all messages at levels from info up to error, to the SYSTEM events log, with a source named Auth-Service:

module.exports = {
    level: 'info',
    transport: 'event',
    event: {
        eventLog: 'SYSTEM',
        source: 'Auth-Service'
    }
}

Removal

To remove HAS as a Windows service, open the PowerShell and execute the following commands from the installation directory of the Helix Authentication Service.

> net stop helixauthentication.exe
> node .\bin\uninstall-windows-service.js