                            Release Notes for
                        P4 Authentication Service (P4AS)
                            Version 2025.2


Introduction

    The P4 Authentication Service is a Node.js application that facilitates
    the integration of identity providers supporting either the OpenID Connect
    or SAML 2.0 authentication protocols.

    Perforce numbers releases YYYY.R/CCCCC, for example 2002.2/30547. YYYY is
    the year; R is the release of that year; CCCCC is the bug fix change level.
    Each bug fix in these release notes is marked by its change number. Any
    build includes (1) all bug fixes for all previous releases and (2) all bug
    fixes for the current release up to the bug fix change level.


Important Notes

    Logging out of a Helix Core or Helix ALM client does not invoke a logout
    with the identity provider (IdP). Depending on the IdP, subsequently
    starting a Helix Core or Helix ALM client might result with the user being
    logged in again without the user being prompted to provide credentials.

    P4AS now requires, by default, that both the SAML response and the SAML
    assertion be signed by the identity provider. This addresses vulnerability
    CVE-2022-39299 in the third-party library, node-saml. If your identity
    provider only signs the response, then set SAML_WANT_ASSERTION_SIGNED=false
    in the .env file. If your identity provider only signs the assertion, then
    set SAML_WANT_RESPONSE_SIGNED=false. Currently most identity providers do
    not sign both unless configured otherwise.


Supported Platforms

    Linux (x86_64)
        RHEL 8, 9
        CentOS 8
        Ubuntu 22.04, 24.04

    The above platforms are tested and subject to regression testing on a
    frequent basis. Errors or bugs discovered in these platforms are prioritized
    for correction. Any platform not listed above is not actively tested by
    Perforce.

    Amazon Linux (x86_64)
        2023

    P4AS is known to work on Amazon Linux 2023 when installed and configured
    using the provided shell scripts. Package installation may work but is not
    supported.

    Windows (x86_64)
        10 Pro
        Server 2019

    P4AS is known to work on the Windows systems listed above.


Requirements

    Node.js v24 (LTS)


Documentation

    P4 Authentication Service Documentation at
    https://www.perforce.com/manuals/helix-auth-svc/ details the steps for
    installation, upgrade, and configuration of the authentication service.


Installation

    Linux

        1. From the download page, select the appropriate Linux distribution
           option. For Linux, P4AS is packaged in DEB and RPM formats.

        2. To install, use the appropriate package install command for the
           system, such as `yum` or `apt` for CentOS and Ubuntu respectively.


Upgrade

    The names of the configuration files for IDP_CONFIG_FILE and LOGGING in
    releases prior to 2022.1 ended with the .js extension. With release
    2022.1 the names must now be changed to end with the .cjs extension.

    Package upgrades from releases prior to 2022.1 on CentOS/RHEL systems
    will result in a missing systemd service definition file. To avoid this
    problem, it is necessary to remove the old package and then install the
    new package. After the 2022.1 release, this will not be necessary.


Known Limitations

    No known limitations with the currently released products.


Third Party Licenses

    See the docs/licenses directory for a complete set of third party licenses.


Changes in every release: Bugs Fixed, New Functionality

----------------------------------------------------------------------
New functionality in 2025.2 (2025.2/2867560) (2025/12/10)

    HAS-195 (Change #2806856)
        Add untested/undoc support for outbound proxy via the proxy-from-env
        JavaScript module (https://github.com/Rob--W/proxy-from-env).

    HAS-637 (Change #2840402)
        Allow hiding the home page via a configuration setting.

----------------------------------------------------------------------
Bugs fixed in 2025.2 (2025.2/2867560) (2025/12/10)

    HAS-606 (Change #2841753)
        Setting PROMPT_FOR_AUTHORIZATION no longer results in an infinite loop
        during the authentication process in which the user is continually
        prompted to allow authentication to proceed.

    HAS-631 (Change #2839547)
        Ignore old user and group provisioning key values when upgrading from
        earlier releases.

    HAS-639 (Change #2839258)
        Service will not request client certificates if configuration setting
        ASSUME_CLIENT_AUTHORIZED has been defined.

    HAS-645 (Change #2814147)
        Service honors excludedAttributes for /Users and /Groups via SCIM.

    HAS-632 (Change #2778683)
        Ignore "user-" prefix when updating Perforce user via SCIM.

----------------------------------------------------------------------
Other changes in 2025.2 (2025.2/2867560) (2025/12/10)

    HAS-625 (Change #2839582)
        Helix Authentication Service is now named P4 Authentication Service, and
        HAS is now P4AS. Package names and configuration settings will still use
        the original names for backward compatibility.

    HAS-655 (Change #2849784)
        Update to Node.js v24 in install scripts and Linux packages.

    HAS-620 (Change #2840399)
        Remove support for Ubuntu 20.04.

    HAS-575 (Change #2840438)
        Remove support for Node.js v18.

----------------------------------------------------------------------
New functionality in 2025.1 (2025.1/2758427) (2025/05/05)

    No new features in this release.

----------------------------------------------------------------------
Bugs fixed in 2025.1 (2025.1/2758427) (2025/05/05)

    HAS-607 (Change #2739014)
        Administrative web interface would show an error message stating
        "i.authnContext.join is not a function" when defining more than one
        OIDC identity provider.

    HAS-616 (Change #2741276)
        Ensure unix-dgram module is installed in RPM packages to allow for
        logging via the syslog utility.

    HAS-623 (Change #2749087)
        Trailing blank lines in certificate files caused SAML authentication
        to fail with "keyInfo is not in PEM format or in base64 format".

----------------------------------------------------------------------
Bugs fixed in 2024.2.1 (2024.2/2646386) (2024/08/29)

    HAS-587 (Change #2644856)
        Supports CORS requests to the /requests REST API to enable web-based
        clients to use the authentication functionality.

    HAS-588 (Change #2645859)
        SAML requests would fail if key file contained attribute values
        before the encapsulation boundary ("keyInfo is not in PEM format or
        in base64 format").

----------------------------------------------------------------------
New functionality in 2024.2 (2024.2/2634404) (2024/08/05)

    HAS-523 (Change #2577281)
        Add JavaScript version of configure script to enable easier
        configuration on Windows platforms.

    HAS-547 (Change #2569160)
        Add /liveness route for orchestration systems such as Kubernetes.
        Returns a 200 if the service, and its dependencies such as Redis,
        are available to serve requests.

----------------------------------------------------------------------
Bugs fixed in 2024.2 (2024.2/2634404) (2024/08/05)

    HAS-564 (Change #2597809)
        Certificate files (server.crt and server.key) are now treated as
        configuration files by the packages, and will no longer be
        overwritten after this release.

    HAS-567 (Change #2599531)
        No longer reset unrelated fields in users and groups when making
        changes via the SCIM-based user provisioning feature.

----------------------------------------------------------------------
Other changes in 2024.2 (2024.2/2634404) (2024/08/05)

    HAS-502 (Change #2590747)
        Remove support for Node.js v16.

    HAS-554 (Change #2583773)
        Remove support for CentOS/RHEL 7.

    HAS-559 (Change #2591399)
        Add package builds for Ubuntu 24.04 (Noble Numbat).

----------------------------------------------------------------------
New functionality in 2024.1 (2024.1/2571580) (2024/03/13)

    HAS-230 (Change #2487461)
        Support client certificate via HTTP header for use with a reverse
        proxy that terminates the TLS connection.

    HAS-434 (Change #2482025)
        Add support for the use of wildcards to specify the SP entity
        identifiers in the `IDP_CONFIG_FILE` file.

    HAS-495 (Change #2512934)
        Allow multiplexing within the user provisioning feature, connecting
        multiple cloud service providers to multiple Helix Core Servers.

    HAS-501 (Change #2507978)
        Support configuration via a TOML file named config.toml as an
        alternative to using the .env file and its numerous supporting
        files.

----------------------------------------------------------------------
Bugs fixed in 2024.1 (2024.1/2571580) (2024/03/13)

    HAS-489 (Change #2485834)
        When not enabled, the static content for the administrative
        interface will no longer be served to the client.

----------------------------------------------------------------------
Other changes in 2024.1 (2024.1/2571580) (2024/03/13)

    HAS-425 (Change #2522538)
        Renaming a user via the user provisioning feature is now disabled by
        default as that can cause complications that would otherwise be a
        surprise to the administrator.

    HAS-506 (Change #2521922)
        The /status route can be disabled by setting STATUS_ENABLED=false

----------------------------------------------------------------------
New functionality in 2023.2 (2023.2/2479541) (2023/08/24)

    HAS-412 (Change #2451243)
        Introduction of web-based administrative interface.

    HAS-424 (Change #2432630)
        REST API for validating Swarm integration with HAS.

----------------------------------------------------------------------
Bugs fixed in 2023.2 (2023.2/2479541) (2023/08/24)

    HAS-435 (Change #2437976)
        Redis connector was creating too many clients.

----------------------------------------------------------------------
Other changes in 2023.2 (2023.2/2479541) (2023/08/24)

    HAS-404 (Change #2426954)
        Support for Node.js v14 has been removed from install script.

    HAS-466 (Change #2467457)
	Configure script will write the bearer token to a file rather than
        storing in the configuration file.

    HAS-468 (Change #2467458)
        Configure script will put the p4 ticket as the P4PASSWD in the .env
        configuration file.

----------------------------------------------------------------------
New functionality in 2023.1 (2023.1/2422401) (2023/03/24)

    HAS-216 (Change #2387345)
        New setting PROMPT_FOR_AUTHORIZATION that when set to any value will
        prompt the user during the authentication process before proceeding
        to the configured identity provider. This prevents phishing attacks.

----------------------------------------------------------------------
Bugs fixed in 2023.1 (2023.1/2422401) (2023/03/24)

    HAS-420 (Change #2415543)
        Replace UNLINK Redis command usage with DEL to support older
        releases of Redis, such as on CentOS 7.4 when installing Redis from
        the EPEL repository. This fixes an issue in which the cached user
        object would remain in the Redis store for up to 5 minutes rather
        than being removed immediately.

----------------------------------------------------------------------
Other changes in 2023.1 (2023.1/2422401) (2023/03/24)

    HAS-249 (Change #2373094)
        Support for the pm2 process manager was removed from the install and
        configure scripts. The use of pm2 is still possible by writing your
        own ecosystem configuration file.

    HAS-314 (Change #2373224)
        Packages for Ubuntu 16.04 are no longer provided.

    HAS-377 (Change #2371506)
        The SAML_WANT_RESPONSE_SIGNED and SAML_WANT_ASSERTION_SIGNED
        settings will now default to `true` such that the SAML response and
        assertion from the identity provider must be signed. Previous
        releases only required that one of these was signed.

----------------------------------------------------------------------
New functionality in 2022.2 (2022.2/2369727) (2022/11/14)

    HAS-279 (Change #2242671)
        New setting SENTINEL_CONFIG_FILE to configure support for Redis
        Sentinel, allowing failover support with multiple Redis instances.

    HAS-282 (Change #2252496)
        New acsUrls and acsUrlRe settings in the IDP_CONFIG_FILE to allow
        for multiple Swarm instances connecting with the same SP entity ID.

    HAS-298 (Change #2266157)
        New setting OIDC_TOKEN_SIGNING_ALGO to specify the signing algorithm
        used by the identity provider to sign the ID token.

    HAS-300 (Change #2299350)
        New setting named OIDC_SELECT_ACCOUNT that will enable users logging
        in via OIDC to select an account with which to authenticate.

----------------------------------------------------------------------
Bugs fixed in 2022.2 (2022.2/2369727) (2022/11/14)

    HAS-339 (Change #2312088)
        Setting IDP_CONFIG_FILE can now be a relative path.

    HAS-351 (Change #2317348)
        Configure script is now compatible with CentOS 7.

    HAS-361 (Change #2340090)
        Perforce user passwords now properly assigned if `password` is
        provided via user add/update via SCIM user provisioning.

----------------------------------------------------------------------
New functionality in 2022.1 (2022.1/2354333) (2022/06/09)

    HAS-146 (Change #2196429)
        Support for SCIM-based user and group provisioning.

    HAS-235 (Change #2209698)
        Install script and package install will create a 'perforce' user and
        group to own the files and run the service.

    HAS-273 (Change #2234881)
        Support for client certificates when connecting to Redis.

----------------------------------------------------------------------
Bugs fixed in 2022.1 (2022.1/2354333) (2022/06/09)

    HAS-261 (Change #2205539)
        Updating the yum package will no longer remove the systemd service
        definition from this version onward.

    HAS-274 (Change #2232214)
        Logging to a file will continue even if an uncaught exception occurs.

----------------------------------------------------------------------
New functionality in 2021.2 (2021.2/2186511) (2021/09/23)

    HAS-217 (Change #2148535)
        Allow using [] for setting multiple values for SAML_AUTHN_CONTEXT in
        the .env configuration file.

    HAS-218 (Change #2147565)
        Support PFX certificate files as well as a passphrase for the
        private key component of the TLS certificate.

----------------------------------------------------------------------
Bugs fixed in 2021.2 (2021.2/2186511) (2021/09/23)

    HAS-225 (Change #2162386)
        Use latest version of node-saml library to prevent configuring the
        service in such a manner as to allow a SAML MITM attack.

    HAS-226 (Change #2168428)
        Configure script now recommends setting IDP_CERT_FILE when
        configuring for SAML to avoid a possible MITM attack.

----------------------------------------------------------------------
New functionality in 2021.1 (2021.1/2135349) (2021/05/27)

    HAS-187 (Change #2090469)
        New setting SAML_IDP_METADATA_FILE to specify IdP metadata from a
        file, as an alternative to the SAML_IDP_METADATA_URL setting.

----------------------------------------------------------------------
Other changes in 2021.1 (2021.1/2135349) (2021/05/27)

    HAS-164 (Change #2082598)
        Use systemd to manage the P4AS instance instead of pm2. Configure
        script and packages will install and start P4AS as a service unit.

    HAS-181 (Change #2075199)
        Single binary build of P4AS for Linux packages, no need for Node.js.

----------------------------------------------------------------------
New functionality in 2020.2 (2020.2/2065968) (2021/01/28)

    HAS-21 (Change #2041029)
        Scripts are now available to install and remove P4AS as a Windows
        service.

    HAS-79 (Change #2035660, 2035664, 2035665)
        You can now run P4AS behind a proxy, with the option of storing
        session information in Redis to enable failover, with the addition
        of rule-based routing without Redis.

    HAS-141 (Change #2037047)
        You can now run P4AS in a Docker container, which is available on
        Docker Hub (https://hub.docker.com/r/perforce/helix-auth-svc).

----------------------------------------------------------------------
Bugs fixed in 2020.2 (2020.2/2065968) (2021/01/28)

    HAS-162 (Change #2035660, 2035664, 2035665)
        Fixed issue with SameSite cookie policy enforcement in newer
        browsers by enabling load balancer support (see also HAS-79).

----------------------------------------------------------------------
Other changes in 2020.2 (2020.2/2065968) (2021/01/28)

    HAS-168 (Change #2037742)
        Upgrade Node.js requirement to version 14 (from 12).

----------------------------------------------------------------------
New functionality in 2020.1.1 (2020.1.1/2032266) (2020/11/03)

    HAS-153 (Change #2020849)
        Package for Ubuntu version 20.04.

----------------------------------------------------------------------
Bugs fixed in 2020.1.1 (2020.1.1/2032266) (2020/11/03)

    HAS-43
        URL not sent to user logging in to edge server.
        Caused by P4-19549 in Helix Core Server, fixed in 2019.1.11,
        2019.2.8, 2020.1.1, and 2020.2 releases.

    HAS-154 (Change #2020788)
        Swarm integration broken by browser content security policy.

----------------------------------------------------------------------
New functionality in 2020.1 (2020.1/2016391) (2020/09/24)

    HAS-143 (Change #2014015)
        Linux-based configuration script supports Amazon Linux 2.

----------------------------------------------------------------------
Bugs fixed in 2020.1 (2020.1/2016391) (2020/09/24)

    HAS-106 (Change #2000728, 2000731)
        Certificate message digest caused extension connection to fail.

----------------------------------------------------------------------
New functionality in 2019.1.1.000002

    HAS-91 (Change #1991037)
        Linux-based configuration script to assist in configuring HAS.

----------------------------------------------------------------------
Bugs fixed in 2019.1.1.000002

    HAS-111 (Change #2001802)
        The install.sh starts pm2 as the current user, not as root on CentOS.

    HAS-118 (Change #2003138)
        Login error in browser: request identifier must be defined

    HAS-119 (Change #2003163)
        Remove color codes from auth service log output.

    HAS-121 (Change #2003544)
        Exception when CA_CERT_PATH directory contains an empty directory.

----------------------------------------------------------------------
New functionality in 2019.1.1.000001

    HAS-23 (Change #1876368)
        Support file patterns for finding certificate authority (CA) files.

    HAS-24 (Change #1875394)
        Allow specifying the bind address for the server.

    HAS-25 (Change #1876395)
        Permit specifying the SAML identity provider certificate.

    HAS-26 (Change #1899075)
        Support specifying a CA path in addition to a single file.

    HAS-35 (Change #1910276)
        Added the OIDC_CLIENT_SECRET_FILE setting because we discourage the
        use of OIDC_CLIENT_SECRET.

    HAS-36 (Change #1914136)
        Support logging to syslog rather than plain file.

    HAS-40 (Change #1917932)
        Support filtering client requests by certificate common name.

----------------------------------------------------------------------
Bugs fixed in 2019.1.1.000001

    HAS-29 (Change #1884852)
        Azure login blocked with error regarding authn context value.

    HAS-34 (Change #1907004)
        Throws EISDIR error when reading certificates.

    HAS-46 (Change #1954444)
        OIDC needs to support Authorization Code with PKCE.

    HAS-50 (Change #1956618)
        Auth via SAML and Swarm fails validation in core extension.

    HAS-51 (Change #1958835)
        Updated SAML validate endpoint should require client certs.

----------------------------------------------------------------------
2019.1

    Initial release
