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

P4 Authentication Service Documentation | 2025.1

# 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 P4 Authentication Service 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 P4 Authentication Service 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 P4 Authentication Service, 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, P4 Authentication Service might need to request a specific SAML name identifier format. For example, with Azure AD and SAML, if the configuration for P4 Authentication Service 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 P4 Authentication Service, 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.`

P4 Authentication Service, 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 P4 Authentication Service 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

With Helix Swarm 2024.1 and later, configuration between P4 Code Review and P4 AS is no longer needed. The following is relevant for P4 Code Review 2018.3 through 2023.4.

The connection between P4 Authentication Service and P4 Code Review 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 P4 Authentication Service `.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 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 P4 Authentication Service 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”, two possible causes are:

- The system clocks of the IdP and the machine running P4 Authentication Service are not in sync. If so, 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.

- The certificate used by the authentication service does not match what the identity provider has in its configuration. If the IdP is configured to expect the SAML authentication request to be signed and/or encrypted, check whether the auth service cert has changed recently.

## Error: SAML assertion audience mismatch

The web browser and the log file might contain an entry similar to the following:

Error: SAML assertion audience mismatch. Expected: https://has.example.com/ Received: https://has.example.com

This indicates that P4 Authentication Service is not configured to exactly match the IdP's authentication response. In this case, remove the extra trailing slash in the SAML_SP_AUDIENCE setting, and restart the service.

Your search for returned results