Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 Authentication Service Documentation | 2025.1

# Installing

There are four ways to install P4 AS as an application, plus the alternative of installing P4 Authentication Service 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 P4 AS 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 P4 Server authentication instead of P4 AS. See the Authorizing Access in the P4 Server Administration Documentation.

- Two valid certificates:

  - A server certificate for P4 Authentication Service.

  - A client certificate for the other half of the solution, such as:

    - P4 Server Extension

    - P4 Code Review

    - Perforce ALM License Server

    - P4 Plan Server

    See After configuring and starting

- One or more of the following:

> Product | Note
> --- | ---
> P4 Server, version 2019.1 or later | You must have knowledge of P4 administration for authentication with tickets - see Authenticating using passwords and tickets in the P4 Server Administration Documentation. To configure P4 AS for Helix Core Server (P4D) and a P4 client, such as the P4 Visual client (P4V) or P4 Sync, you must configure a P4 Server Extension. See the Administrator's Guide for Helix Authentication Extension in the docs directory of the Helix Authentication Extension repository on GitHub. The Helix Authentication Extension provides a mechanism to test the P4 AS 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.
> Perforce ALM, version 2019.4 or later, or Surround SCM, version 2019.2 or later | To use the P4 AS to authenticate from Perforce ALM or Surround SCM, you must configure Helix ALM License Server. see the Helix ALM License Server Admin Guide.
> P4 Plan 11.0 or later | See Integrating with identity providers for single sign-on in the P4 Plan System Administrator Guide

### Multi-factor authentication

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

We do not recommend using the Helix MFA Authenticator with P4 AS. 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 as an application

You can install P4 AS as an application by using any of the following:

Method | Note
--- | ---
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: Node.js, version 20 or later - see Easy way to install Node.js a process manager module dependencies

## 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 P4 Authentication Service. Do not run P4 Authentication Service with the Linux `root` user account.

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

2. Install the `helix-auth-svc` package:

- For APT, run `sudo apt-get install helix-auth-svc`

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

- For YUM, run `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 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.

The installation script creates an operating system user account named `perforce` and a group named `perforce` for running P4 Authentication Service. Do not run P4 Authentication Service with the Linux `root` user account.

### Installation steps

1. Download P4 AS 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.

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.

7. 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.
8. For better security, replace the example self-signed SSL certificates with ones signed by a trusted certificate authority.
9. 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.

1. Download P4 AS 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 package.json file.
4. Create an operating system user account named `perforce` and a group named `perforce` for running P4 Authentication Service. Do not run P4 Authentication Service with the Linux `root` user account.

### Easy way to install Node.js

If you are going to do a manual installation of P4 Authentication Service, 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. Install the module dependencies:
   1. Open a terminal window.
   2. Use the cd command to change to the directory containing the service code. This is the directory that was created when you extracted the .zip or tar.gz file.
   3. Verify that this directory has the package.json file, and run:
      npm install
      which copies dependencies from the Node.js package site into the node_modules directory within P4 AS.

### 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. Install the module dependencies:
   1. Open a terminal window.
   2. Use the cd command to change to the directory containing the service code. This is the directory that was created when you extracted the .zip or tar.gz file.
   3. Verify that this directory has the package.json file, and run:
      npm install
      which copies dependencies from the Node.js package site into the node_modules directory within P4 AS.

## Windows service installation

P4 AS can be deployed to Windows-based systems, and managed as a Windows service.

1. Download the zip file for the service from Downloads.

   1. Select P4 Clients, Plugins, and Integrations > P4 Authentication Service > Download > Family - Platform Independent > Platform - OS Independent > Version - zip > Download.

   2. Extract the zip file.

2. Download and run both:
   1. The Windows-based installer for Git because it is a precondition for installing the Node.js runtime environment.
   2. The Windows-based installer for Node.js LTS for Long Term Support.
3. Install the module dependencies.
   1. Open a Windows PowerShell window as an administrator.
   2. Change to the directory containing the authentication service.
   3. Run the following commands:

> > Copy

> >     1
> >     2
> >     3
> >     4
> >     cd helix-authentication-service
> >     npm ci --omit=dev --omit=optional
> >     npm install --omit=dev --omit=optional node-windows
> >     node .\bin\install-windows-service.js

(Although you can run the commands as a normal user, several User Access Control prompts will request your permission.)

P4 Authentication Service is now installed and running as a Windows service. When the system restarts, the service starts automatically.

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 Window Service

You can start and stop the P4 Authentication Service 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 Windows service installation. 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: Stop the service. Add these lines to the .env file: `SVC_BASE_URI=https://has.example.com` `LOGGING='file://C:\\helix-auth-svc\\logging.config.cjs'` 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`:

Copy

    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 P4 Authentication Service as a Windows service, open the PowerShell and execute the following commands from the installation directory of P4 AS.

    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.

Your search for returned results