Installing Helix Authentication Service

Prerequisites

• Administrative expertise with the software of your Identity Provider
• Expertise in security administration sufficient to work with both your Identity Provider (IdP) and your Perforce server product.

• A web browser. Any client using the authentication service requires a web browser.

• 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 Perforce authentication instead of Helix Authentication Service. See the Authorizing Access in the Helix Core Server Administrator Guide.

• Two valid certificates: a certificate for HAS and a certificate for the other half of the solution, which is either a Helix Core Server Extension or a Helix ALM License Server.

• One or more of the following:

  Helix Core Server, version 2019.1 or later, assuming that you have knowledge of Perforce administration for authentication with tickets - see Authenticating using passwords and tickets in the Helix Core Server Administrator Guide. Important To configure Helix Authentication Service for Helix Core Server (P4) and the Helix Core visual client (P4V), you must configure a Helix Core Server Extension. See the Administrator's Guide for Helix Authentication Extension in the docs directory of the Helix Authentication Extension repository on GitHub. Extensions are currently disabled for Helix Core installs on Windows servers. The Helix Authentication Extension provides a mechanism to test the Helix Authentication Service with a select group of users prior to rolling out the service organization-wide. See the Testing the extension section in the Administrator's Guide for Helix Authentication Extension in the docs directory of the Helix Authentication Extension repository on GitHub.

  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.

  Note

  The diagrams at Sequence for Helix Core and Sequence for Helix ALM show the flow of information between three components:

  • the IdP
  • Helix Authentication Service
  • Helix Core Extension (or ALM License server)

  The installation and configuration of these three components can be in any order. What matters is that each component have the information it needs to do its part in the sequence.

  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

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

Package installation overview	Easiest way Supports CentOS 7, 8 Ubuntu 16, 18, 20 Requires an installation of Node.js, version 14 or later
Installation script	Supports CentOS/RHEL 7, 8 Debian 8, 9, 10 RedHat Fedora 31 Ubuntu 14, 16, 18, 20 Automates the installation of required software, including Node.js Requires some installation steps
Manual installation	Supports CentOS/RHEL 6, 7, 8 Fedora 31 Ubuntu 14, 16, 18, 20 other Linux distributions (untested) Windows 10 Pro and Windows Server 2019, which are supported for use with the Helix ALM License Manager are not supported for use with Helix Core Requires an installation of: Node.js, version 14 or later a process manager module dependencies
Docker	Even easier than the package installation is the pre-build Docker container for download. For more information, see https://hub.docker.com/r/perforce/helix-auth-svc

Only the Installation script automatically installs Node.js, so if you will be using the package installation (see Package installation overview) or the Manual installation, you need get Node.js installed.

Easy way to install Node.js

You can install Node.js on the following flavors on Linux.

Installing Node.js on Ubuntu

14, 16, and 18
Packages from NodeSource are easy to install: $ sudo apt-get install build-essential curl git $ curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash - $ sudo apt-get install nodejs

Installing Node.js on CentOS/RHEL 7

CentOS, Oracle Linux, and RedHat Enterprise Linux lack Node.js packages of the versions required by this service, but there are packages available from NodeSource that are easy to install.

$ sudo yum install curl git gcc-c++ make
$ curl -sL https://rpm.nodesource.com/setup_14.x | sudo -E bash -
$ sudo yum install nodejs

Installing Node.js on CentOS/RHEL 8

$ sudo yum install curl git gcc-c++ make

$ curl -sL https://rpm.nodesource.com/setup_14.x | sudo -E bash -
$ dnf --repo=nodesource download nodejs
$ sudo rpm -i --nodeps nodejs-14.*.rpm
$ rm -f nodejs-14.*.rpm

Installing Node.js on Fedora 31

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

$ sudo dnf install nodejs

Package installation overview

If your operating system is CentOS 7, 8 or Ubuntu 16, 18:

1. Make sure you have an installation of Node.js, version 14 or later (see Easy way to install Node.js ).

2. Perform the package installation that allows you to use the YUM or APT package manager.

Package installation details

Package installation requires sudo or root level privileges.

Verify the Public Key

To ensure you have the correct public key for installing Perforce packages, verify the fingerprint of the Perforce public key against the fingerprint shown below.

1. Download the public key at https://package.perforce.com/perforce.pubkey
2. To obtain the fingerprint of the public key, run:

   gpg --with-fingerprint perforce.pubkey

3. Verify that it matches this fingerprint:

   E581 31C0 AEA7 B082 C6DC 4C93 7123 CB76 0FF1 8869

Follow the instructions that apply to you:

• For APT (Ubuntu)
• For YUM (Red Hat Enterprise Linux or CentOS)

For APT (Ubuntu)

1. Add the Perforce packaging key to your APT keyring. For example,

   wget -qO - https://package.perforce.com/perforce.pubkey | sudo apt-key add -

2. Add the Perforce repository to your APT configuration.

   Create a file called /etc/apt/sources.list.d/perforce.list with the following line:

   deb http://package.perforce.com/apt/ubuntu {distro} release

   Where {distro} is replaced by one of the following: precise, trusty, xenial or bionic.

3. Run apt-get update
4. Install the package by running sudo apt-get install helix-auth-svc

Alternatively, you can browse the repository and download a Deb file directly from https://package.perforce.com/apt/

For YUM (Red Hat Enterprise Linux or CentOS)

1. Add Perforce's packaging key to your RPM keyring:

   sudo rpm --import https://package.perforce.com/perforce.pubkey

2. Add Perforce's repository to your YUM configuration.

   Create a file called /etc/yum.repos.d/perforce.repo with the following content:

   [perforce]
   name=Perforce
   baseurl=http://package.perforce.com/yum/rhel/{version}/x86_64
   enabled=1
   gpgcheck=1

   where version is either 6 for RHEL 6 or 7 for RHEL 7

3. Install the package by running sudo yum install helix-auth-svc

   Alternatively, you can browse the repository and download an RPM file directly from https://package.perforce.com/yum/

Next

See the configuration steps in the Configuring Helix Authentication Service section.

Installation script

If your operating system is not supported by the package installation, we recommend using the installation script rather than performing a Manual installation. The installation script supports:

• CentOS 7, 8
• Debian 8, 9, 10
• RedHat Fedora 31, RHEL 7 and 8
• Ubuntu 14, 16, and 18

Installation steps

1. Download Helix Authentication Service from the Perforce download page by selecting Plugins & Integrations.

2. Expand the .tgz or .zip file.
3. Verify that you now have a README file, an ecosystem.config.js file, and an install.sh file. The install.sh is the bash installation script.
4. Verify that the bin subdirectory contains the configure-auth-service.sh file.
5. Run the bash script named install.sh, which installs Node.js and the pm2 process manager, and then builds the service dependencies.
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.

6. Modify the service configuration by editing the ecosystem.config.js 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.
7. (Recommended) For better security, replace the example self-signed SSL certificates with ones signed by a trusted certificate authority.
8. Restart the service by using pm2 startOrReload ecosystem.config.js

Next

See the configuration steps in the Configuring Helix Authentication Service section.

Manual installation

The manual installation supports more operating systems than does the package installation.

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.js file.

CentOS/RHEL 6, 7, 8, Fedora 31, Ubuntu 14, 16, 18

1. Make sure you have an installation of Node.js, version 14 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 14 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 Installing as a Windows service .

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

Next

See the configuration steps in the Configuring Helix Authentication Service section.