Networking Single Sign On Troubleshooting

June 29, 2024 at 4:56 AM

This page contains some basic tips for troubleshooting SSO problems.

Can I force a SSO user in a test environment?

During testing or development without having Kerberos/NTLM available it can be useful to force a username so that you can simulate a SSO user. To do so you open the .htaccess file of your WordPress configuration and paste the following line into it

RequestHeader set X-REMOTE-USER "netbios\\username"
# or
# RequestHeader set X-REMOTE-USER "userprincipalname@upnsuffix"

The dashes (“-“) are automatically converted into underscores (““) and an *HTPP* prefix is prepended, resulting in “HTTP_X_REMOTE_USER”. You have to make sure that you have enabled mod_headers in your Apache configuration.

SSO does not work

Next ADI depends on the value of one of the environment variables $_SERVER['REMOTE_USER'], $_SERVER['HTTP_X_REMOTE_USER'] or $_SERVER['X_REMOTE_USER']. One of them must contain the sAMAccountName or userPrincipalName from the Active Directory. Without one of these variables, SSO can’t work.

You can check the variables with these methods:

  • add the file aaa.php with the content <?php var_dump($_SERVER) to your WordPress installation folder. Access the URL url/to/my/wordpress/instance/aaa.php and you will see the whole $_SERVER content.

  • add echo '<script>console.log(`'; var_dump($_SERVER); echo '`);</script>'; to your WordPress’ index.php. The hole $_SERVER content will be displayed inside the browser’s developer console (F12 -> console)

  • since 2.0.11 open the wp-admin page in your browser. The log file contains the detected remote user principal.

  • add var_dump($_SERVER); die(); to your NON PRODUCTIVE WordPress’ index.php. WordPress WILL STOP WORKING but you can see the result when visiting the URL of your WordPress instance.

When REMOTE_USER or X_REMOTE_USER is missing, it is very likely that your webserver and/or Kerberos is not properly configured. Please see SSO with IIS on Windows, Kerberos SSO with Apache on Linux, https://www.johnthedeveloper.co.uk/single-sign-on-active-directory-php-ubuntu or some other Kerberos tutorial.

Please undo the changes (like creating aaa.php or editing the index.php) as soon as possible, because $_SERVER contains some valuable information like OS version or file paths.

I can’t visit the website

Make sure that the clock of the Active Directory host and the webserver host are equal, meaning both using NTP.

Login prompt pops up

If your IIS or Apache keeps asking for the user name or password when using Kerberos, check the following points:

  • Make sure that you access the website with the webserver’s DNS name. Kerberos does only work when you are using the DNS name and not any IP addresses.

  • Make sure that your webbrowser trusts the website (see https://support.pingidentity.com/s/article/How-to-configure-supported-browsers-for-Kerberos-NTLM )

  • Make sure that client’s time is the same on your webserver and the KDC (your Active Directory).

  • Make sure that all client’s Kerberos tickets are recognized by the Active Directory domain. You need setup a domain trust if you want clients from other domains access your website.

  • When switching from test to production environment, you have to check that the hostname of your production environment has a corresponding SPN (service principal name) and that the old SPN is removed.

    We experienced a case where a VM containing a test environment (Windows 2016) had been cloned. During cloning, the hostname of the new VM were changed. The clone contained the new production environment and the old VM were turned off. Due to the change of the hostname, the Active Directory did not contain the correct SPN of the new VM but mapped the SPN to the old VM. Kerberos authentication failed because of the mismatch. We removed the correct SPN from the test environment and added them to the production environment.

No profile found for authentication / No matching suffix found

  • The mod_auth_kerb apache module automatically stripes the realm suffix from the usernames. NADI requires the suffix to determine the correct active directory. You have to set the option KrbLocalUserMapping to off.

Further tips

  • increase the webserver’s log level (for Apache: LogLevel trace8)