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.js 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.js 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.js 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:
- Terminate the pm2 daemon by using the pm2 kill command.
- 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.js file and restart pm2, you might notice your changes do not take effect. The workaround is:
- Stop the pm2 instance started by the non-root user.
- As the root user, restart the pm2 instance.