Fork me on GitHub

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

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

  • Make sure that your webbrowser trusts the website (see https://ping.force.com/Support/PingFederate/Integrations/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.

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)