Troubleshooting

Check the authentication service log file for possible errors. By default, the log is named auth-svc.log and the package installer puts it in /opt/perforce/helix-auth-svc

"Missing authentication strategy" displayed in browser

During the initial setup, it is likely that the settings for the protocol (such as SAML or OIDC) simply have not been defined as yet. Without the necessary protocol settings, the service cannot initialize the authentication "strategy" (the appropriate passport module).

Redirect URI error displayed in browser

In the case of certain identity providers, you may see an error message indicating a "bad request" related to a redirect URI. For instance:

Error Code: invalid_request
Description: The 'redirect_uri' parameter must be an absolute URI that
is whitelisted in the client app settings.

This occurs when the authentication service base URI, SVC_BASE_URI, does not match what the identity provider has configured for the application. For example, when using an OIDC configuration in Okta, the Login redirect URIs must have a host and port that match those found in the SVC_BASE_URI environment variable in the service configuration. You may use an IP address or a host name, but you cannot mix them; either both have an IP address or both have a host name.

Environment settings and unexpected behavior

If the authentication service is not behaving as expected based on the configuration, it might be getting environment variables from an unexpected location. All of the environment variables will be dumped to the console when debug logging is enabled, so if those do not match your expectations, verify that you are using one but not both of the following:

• a .env file or
• an ecosystem.config.cjs file

Although you can have both files, the order of precedence is not defined, so you might get unexpected results. In practice, it appears that the .env file takes precedence over the env section in the ecosystem.config.cjs file, but that is not a safe assumption.

pm2 caching environment variables

If you remove an environment variable (for instance, by removing it from the env section of the ecosystem.config.cjs file) and restart the service, the pm2 daemon might cache the old value for that variable. This is especially true when pm2 is running in production or cluster mode (when NODE_ENV is set to production).

To clear the cached values:

1. Terminate the pm2 daemon by using the pm2 kill command.
2. Start the service again by using the pm2 start auth-svc command.

OIDC challenge methods not supported

Some OpenID Connect identity providers might not be configured to have a default code challenge method. As a result, user authentication might fail, and the service log file will contain an error like the following:

error: oidc: initialization failed: code_challenge_methods_supported is not properly set on issuer ...

If this happens, set the OIDC_CODE_CHALLENGE_METHOD, which is described at OpenID Connect settings, to S256 and restart the authentication service.

pm2 restart has no effect for CentOS service package

If you installed HAS on on CentOS using the service package, after you modify the ecosystem.config.cjs file and restart pm2, you might notice your changes do not take effect. The workaround is:

1. Stop the pm2 instance started by the non-root user.
2. As the root user, restart the pm2 instance.

Chrome does not allow login

• If the user cannot log in when using Chrome, but succeeds with other browsers, try setting TRUST_PROXY.

• Error message "did not find expected authorization request details in session, req.session["oidc:{HOSTNAME} is undefined" might occur if using Chrome with a HAS client configured for http not https. The workaround is to use https, which we recommend for production environments, or try using the Firefox browser.

Azure AD and a SAML nameID that appears to be random

When a user logs in through HAS, the "login successful" page shows the user's unique identifier. This is usually an email address. If, for some users, the value shown appears to be a long, random string of letters and numbers, HAS might need to request a specific SAML name identifier format. For example, with Azure AD and SAML, if the configuration for HAS does not specify a SAML_NAMEID_FORMAT setting, the default allows Azure to use what might appear to be a random value. To change this behavior, see SAML_NAMEID_FORMAT.

Azure AD SAML authentication method mismatch

If a user of Azure AD for SAML authentication cannot authenticate through HAS, the error message might be similar to the following:

Message: AADSTS75011: Authentication method 'X509, MultiFactor' by which the user authenticated with the service doesn't match requested authentication method 'Password'. Contact the Perforce Helix Core - Helix Authentication Service application owner.

HAS, by default, sets the SAML authentication context to PasswordProtectedTransport. This might not match if Azure AD is expecting what it calls "MultiFactor" authentication instead of password-based authentication.

The workaround is to set SAML_AUTHN_CONTEXT to a list of authentication contexts, if you know which contexts Azure AD would expect you to list.

Alternatively, use the value urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified to indicate that you are not specifying PasswordProtectedTransport or any other authentication context.

This is secure because Azure AD always uses its own criteria for determining the user's authenticity. The role of HAS is to establish the authenticity of Perforce, not the authenticity of the user.

SAML "Invalid signature" or "Invalid document signature"

For SAML, when the user attempts to authenticate, the web browser might show an error if it expects a signature that is missing:

• "Invalid signature" means the SAML assertion is not signed

• "Invalid document signature" means the SAML response is not signed

Such errors might originate with the passport-saml library of Node.js that rejects having both the SAML response and the SAML assertion be unsigned. Depending on the version of the passport-saml library, it might be necessary that both be signed.

To resolve this sort of problem, see the final step for your IdP in Example Identity Provider configurations.

Swarm troubleshooting

The connection between HAS and Swarm require entering information into configuration files of different formats on different systems, which can be prone to errors. To help you debug the connection configuration, use the validation script.

1. Enable the validation script by setting VALIDATE_ENABLED to “true” in the HAS .env configuration file. This exposes the /validate/swarm REST API.

2. On the Swarm system, use a curl command to validate your Swarm config file.

This example curl command implicitly uses POST because of the -F argument:

curl -k -F config=@path/to/config.php https://has.example.com/validate/swarm

If the response is {"status": "ok"}, no problems are detected.

If the response is "status": "errors"}, the input is malformed.

If the response is "status": "results"}, the response includes a list of the mismatching data. For example:

{"results":["saml.sp.assertionConsumerService.url must be http://swarm.example.com",
"saml.idp.singleSignOnService.url must be https://has.example.com/saml/sso"],"status":"results"}

indicates two problems with the Swarm configuration.

(a) The leading part indicates that the saml.sp.assertionConsumerService.url in the Swarm configuration file has an incorrect value.

Note that saml.sp.assertionConsumerService.url refers to this part of the Swarm config.php file:

'saml' => array(
    'sp' => array(
        'assertionConsumerService' => array(
            'url' => 'https://swarm.doc:8043',

(b) The second part indicates that the saml.idp.singleSignOnService.url has an incorrect value.

‘Authentication Failed’ and 403 error in the HAS log file

If you encounter a situation in which the IdP reports success but the application says ‘Authentication Failed’ or similar and there is a 403 error in the HAS log file:

1. Specify the location of the root CA as CA_CERT_FILE in the .env configuration file.

2. If there are intermediate CAs, add them all with the root CA to a folder and specify CA_CERT_PATH instead in the .env file.

Error: SAML assertion not yet valid

If you see “Error: SAML assertion not yet valid”, ask your network administrator to ensure that the system clock is in agreement between the IdP and the machine running HAS. A possible solution is to configure the ntpd operating system daemon that synchronizes the system clock to remote Network Time Protocol servers. To learn more, see ntpd - Network Time Protocol (NTP) daemon.