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

Further tips

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