Installing

There are four ways to install Helix Authentication Service as an application, plus the alternative of installing HAS as a Windows service.

Prerequisites

  • Administrative expertise with the software of your Identity Provider (IdP)
  • Expertise in security administration sufficient to work with both your IdP and your Perforce server product.
  • A web browser. Any client using the authentication service requires a web browser.

  • Source code for Helix Authentication Service from the Downloads page (or from the GitHub repository).
  • Any client (even the p4 command-line client) is still required to authenticate through your IdP's website. We recommend that at least one user with super level access use Helix Core Server authentication instead of Helix Authentication Service. See the Authorizing Access in the Helix Core Server Administrator Guide.

  • Two valid certificates:

    • a server certificate for HAS

    • a client certificate for the other half of the solution, such as:

      • Helix Core Server Extension

      • Helix Swarm

      • Helix ALM License Server

      • Helix Plan Server (formerly known as Hansoft Server)

      See After configuring and starting HAS

  • One or more of the following:
  • Helix Core Server, version 2019.1 or later
    Important

    Helix ALM, version 2019.4 or later, or Surround SCM, version 2019.2 or later

    Important

    To use the Helix Authentication Service to authenticate from Helix ALM or Surround SCM, you must configure Helix ALM License Server. see the Helix ALM License Server Admin Guide.

    Hansoft Server 11.0 or later See Integrating with identity providers for single sign-on in the Hansoft System Administrator Guide
Important

To understand the flow of information between the IdP, HAS, and the component that represents the product server, see the diagrams that applies for you:

Tip

If you want to use multi-factor authentication (MFA) with the Helix Authentication Service, consider using the multi-factor authentication solution provided by your IdP.

We do NOT recommend using the Helix MFA Authenticator with Helix Authentication Service. The Helix MFA Authenticator should only be implemented when your password store and MFA service are separated. The typical use case for the Helix MFA Authenticator is to have an on-prem password store (such as LDAP) and a cloud-based MFA service.

Four ways to install HAS as an application

You can install Helix Authentication Service (HAS) as an application by using any of the following:

Docker

The easiest option is the pre-build Docker container for download. For more information, see https://hub.docker.com/r/perforce/helix-auth-svc

Package installation

 

The next easiest option is the package installation.

Supported operating systems for package installation:

  • CentOS 8
  • RHEL 9
  • Ubuntu 20, 22, 24

Installation script

 

Supported operating systems for the installation script:

  • CentOS/RHEL 8, 9
  • Debian 8, 9, 10
  • RedHat Fedora 31
  • Ubuntu 16, 18, 20, 22, 24
  • Automates the installation of required software, including Node.js
  • Requires some installation steps.
  • Manual installation

     

    Supported operating systems for manual installation

    • CentOS/RHEL 8, 9
    • RedHat Fedora 31
    • Ubuntu 16, 18, 20, 22, 24
    • other Linux distributions (untested)
    • Windows 10 Pro and Windows Server 2019

    Requires an installation of:

    Package installation

    If your operating system is one of the Supported operating systems for package installation:, perform the package installation because it allows you to use the YUM or APT package manager.

    Package installation requires sudo or root level privileges.

    A package installation creates an operating system user account named perforce and a group named perforce for running HAS. Do not run HAS with the Linux root user account or a Windows administrator account.

    1. Follow the instructions for how to configure APT or YUM repositories at Perforce Packages.

    2. Install the helix-auth-svc package:

    Next

    See the configuration steps in the Configuring section.

    Installation script

    If your operating system is not one of the Supported operating systems for package installation: but is one of the Supported operating systems for the installation script:, we recommend using the installation script rather than performing a Manual installation.

    Note

    The installation script creates an operating system user account named perforce and a group named perforce for running HAS. Do not run HAS with the Linux root user account or Windows Administrator account.

    Installation steps

    1. Download Helix Authentication Service from the Perforce download page by selecting Plugins & Integrations.
    2. For Family, choose Platform Independent, select TGZ or ZIP, and Download.
    3. Expand the downloaded .tgz or .zip file.
    4. Verify that you now have a README file, an example.env file, and an install.sh file. The install.sh is the bash installation script.
    5. Verify that the bin subdirectory contains the configure-auth-service.sh file.
    6. Run the bash script named install.sh, which installs Node.js and then builds the service dependencies.
    7. Note

      When you type

      ./install.sh -h

      the output is:

      Installation script for authentication service.
      Usage:
      install.sh [-m] [-n]
      Description:
      Install the authentication service and its dependencies.
      -m
      Monochrome; no colored text.
      -n
      Non-interactive; does not prompt for confirmation.
      -h | --help
      Display this help message.

    8. Modify the service configuration by creating your own editing the .env file. Configuration consists of defining the identity provider (IdP) details for either OIDC or SAML, and setting the SVC_BASE_URI of the authentication service.
    9. (Recommended) For better security, replace the example self-signed SSL certificates with ones signed by a trusted certificate authority.
    10. Restart the service by using the systemctl restart helix-auth command. (The systemctl command is part of the systemd process manager for Linux.)

    Next

    See the configuration steps in the Configuring section.

    Manual installation

    If your operating system in not one of the Supported operating systems for package installation: or Supported operating systems for the installation script:, it might be one of the Supported operating systems for manual installation.

    Note

    We recommend that you create an operating system user account named perforce and a group named perforce for running HAS. Do not run HAS with the Linux root user account or Windows Administrator account.

    Easy way to install Node.js

    If you are going to do a manual installation of HAS, a prerequisite is an installation of Node.js. Various packages for Node.js make it easy to install Node.js.

    Installing Node.js on Ubuntu

    16, 18, 20, 22

    Packages from NodeSource are easy to install:

    $ sudo apt-get install build-essential curl git
    $ curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    $ sudo apt-get install nodejs

    Installing Node.js on CentOS/RHEL 8

    $ sudo yum install curl git gcc-c++ make
    $ curl -sL https://rpm.nodesource.com/setup_20.x | sudo -E bash -
    $ dnf --repo=nodesource download nodejs
    $ sudo rpm -i --nodeps nodejs-20.*.rpm
    $ rm -f nodejs-20.*.rpm

    Installing Node.js on RedHat Fedora 31

    This release of RedHat Fedora provides a compatible version of Node.js, so installation is simple.

    $ sudo dnf install nodejs

    CentOS/RHEL 8, RedHat Fedora 31, Ubuntu 16, 18, 20, 22

    1. Make sure you have an installation of Node.js, version 20 or later (see Easy way to install Node.js ).
    2. Perform the step under Installing Module Dependencies.

    Other Linux distributions

    1. Download and install the Linux Binaries for Node.js, version 20 or later, making sure that the bin folder is added to the PATH environment variable when installing and starting the service.
    2. Perform the step under Installing Module Dependencies.

    Windows 10 Pro and Windows Server 2019

    1. Download and run both:
      1. the Windows-based installer for Git because it is a precondition for installing Node.js
      2. the Windows-based installer for Node.js LTS
    2. Perform the step under Installing Module Dependencies.

    Note that Windows native toolchain, available by installing the Chocolatey Windows package manager, is not required for the authentication service.

    Windows as a service

    If you want HAS to run automatically as a service, see Windows service installation.

    Installing Module Dependencies

    The following command copies dependencies from the Node.js package site into the node_modules directory within HAS. Open a terminal window and change to the directory containing the service code, then run:

    $ npm install

    1. Download Helix Authentication Service from the Perforce download page by selecting Plugins & Integrations.
    2. Expand the .tgz or .zip file you downloaded.
    3. Verify that you now have a README file and an ecosystem.config.cjs file.

    Windows service installation

    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 of Windows service

    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:

    cd helix-authentication-service
    npm ci --omit=dev --omit=optional
    npm -g install node-windows
    npm link --omit=dev --omit=optional 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.

    Tip

    If the service does not appear to be installed and running, run the uninstall script and then install a second time.

    node .\bin\uninstall-windows-service.js 
    node .\bin\install-windows-service.js

    Starting and Stopping the HAS Window 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 options for Windows

    Two options:

    Easiest

    Customized

    The easiest configuration is to run the configure-auth-service.js script by using the node binary:

    node .\bin\configure-auth-service.js

    This option assumes that you have an installation of Node.js and Git, and that the administrator has installed the module dependencies by using the npm ci command. See Installation of Windows service.

    This basic Windows configuration does not use Windows event logging and is not connected with Windows service integration.

    The configuration of the authentication service is managed through environment variables. You can set 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='file://C:\\helix-auth-svc\\logging.config.cjs'

    3. Start the service.

    When specifying values in the .env configuration file, you can enclose the values in single (') or double (") quotes. For file paths, you can use a single backslash (\) or double backslashes (\\). The LOGGING setting requires the prefix file:// with double forward slashes.

    For additional settings, see Configuring.

    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'
        }
    }

    Be aware that some versions of node-windows might send all logging to the Application category in the event viewer, despite the value of the eventLog setting above.

    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

    The Windows service can also be stopped from Windows' Services application, where its name is Helix Authentication, however uninstall-windows-service.js must still be run from the shell.

    Next

    See the configuration steps in the Configuring section.