Troubleshooting

"Missing authentication strategy" displayed in browser

Check authentication service log files for possible errors. 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 variables, 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 the 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.

AzureAD 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.