LDAP SSO

Last updated on

9 March 2017

Drupal 7 will no longer be supported after January 5, 2025. Learn more and find resources for Drupal 7 sites

The documentation for enabling SSO (Single Sign On) or "Integrated Windows Authentication" is not specific to Drupal or the Drupal LDAP Modules, but it is specific to the operating system and webserver. The following notes will reference more appropriate documentation when possible.

On Windows, "Integrated Windows Authentication" (formerly called NTLM, and also known as Windows NT Challenge/Response authentication) is the term for SSO where the webserver negotiates authentication. Detailed documentation is available at: http://docs.moodle.org/22/en/NTLM_authentication

On Linux, SSO is handled by Kerberos or Samba/Winbind/NTLM. Detailed documention about setting up Kerberos and Apache with mod_auth_kerb is available: http://www.grolmsnet.de/kerbtut/

Note: Microsoft no longer recommends use of NTLM in applications; see: http://msdn.microsoft.com/en-us/library/cc236715.aspx

Prerequisite #1: Authentication Mechanism for LDAP

To use the single sign-on feature, your web server must provide an authentication mechanism for LDAP. The only authentication mechanism used in development was mod_auth_sspi for Apache/Windows, but so long as the web server's LDAP
authentication mechanism is configured to provide the $_SERVER variable $_SERVER['REMOTE_USER'] or $_SERVER['REDIRECT_REMOTE_USER'] corresponding directly to a user's LDAP user name, this should work all the same. This
will require some sort of LDAP authentication mechanism.

mod_auth_sspi (Recommended) for Apache on Windows is available here: http://mod-auth-sspi.sourceforge.net/
mod_auth_kerb (Recommended) for Apache on Linux is available here: http://modauthkerb.sourceforge.net
mod_ntlm for Apache on Linux is available here: http://modntlm.sourceforge.net
mod_auth_ntlm_winbind for Apache on Linux is available here: http://samba.org/ftp/unpacked/lorikeet

If a Linux distribution is being used, Apache authentication modules are likely available within the distro's package manager.

Prerequisite #2: Set Authentication Requirements for Paths

Unless an administrator wishes to require that all visitors be authenticated, NTLM, Kerberos, and/or basic authentication should be set up only on the path user/login/sso, which will authenticate the visitor, but not deny access to view the site if the visitor is not authenticated. An administrator may wish to
require LDAP authentication to view any portion of the site; this can be
achieved by changing the location directive below to "/". An administrator may also wish to automatically log in visitors to Drupal; this can be achieved by checking "Turn on automated single sign-on" in the module configuration page.

Prerequisite #3: Ensure Clean URLs are Enabled

Clean URLs must be enabled in Drupal in order for LDAP SSO to function properly.
Incorrect:
http://example.com/index.php?q=/user/login/sso
Correct:
http://example.com/user/login/sso
To enable clean urls see Getting Started - Step 6.

Pretest Before Enabling LDAP SSO Module

After enabling and configuring an LDAP authentication module within Apache or IIS, visit http://example.com/user/login/sso in the Drupal installation. With or without the LDAP SSO feature enabled, the browser should prompt for a user name and password if using Internet Explorer 8 or a non-Microsoft browser. Internet Explorer 7 by default will pass authentication credentials to local websites. IE8-10, Chrome, and Firefox can be configured to do this as well.

If prompted for credentials on that path, enter a valid LDAP user name,
omitting the domain if "SSPIOmitDomain On" is configured, as well as a password.
If the credentials are correct, or if credentials are passed automatically
by the browser and successfully authenticated, a Drupal 404 "Page not found" message will be displayed if the module is not enabled; an "access is denied" message will be displayed if the module is enabled and the browser is already logged in; and if the ldap_sso module is fully configured and there is no existing session, the browser will display the message "You have been successfully authenticated" after redirecting to the sites' home page.

Prerequisite #4: Enable LDAP SSO Module and Configure LDAP Authentication

Todo..

Apache on Windows notes

An example of an Apache configuration for a named virtualhost configuration using mod_auth_sspi on Windows is as follows:

httpd.conf:

# Virtual hosts
Include conf/extra/httpd-vhosts.conf

# Pass NTLM authentication to Apache
LoadModule sspi_auth_module modules/mod_auth_sspi.so

<IfModule !mod_auth_sspi.c>
 LoadModule sspi_auth_module modules/mod_auth_sspi.so
</IfModule>

httpd-vhosts.conf:

NameVirtualHost example.com

<VirtualHost example.com>
 DocumentRoot "D:/www/example.com/htdocs"
 ServerName example.com

 <directory "D:/www/example.com/htdocs">
   Options Indexes FollowSymLinks MultiViews
   AllowOverride All
   Order Allow,Deny
   Allow from all
 </directory>

 <Location /user/login/sso>
   AuthType SSPI
   AuthName "Example.com - Login using your LDAP user name and password"
   SSPIAuth On
   SSPIAuthoritative On
   ### The domain used to authenticate with LDAP; this should match the domain
   ### configured in the LDAP integration configuration within Drupal
   SSPIDomain ad.example.com
   SSPIOmitDomain On
   SSPIOfferBasic On
   Require valid-user
   #SSPIBasicPreferred On
   #SSPIofferSSPI off
 </Location>
</VirtualHost>

Apache on Linux notes

An example of an Apache configuration for a named virtualhost configuration using mod_auth_kerb on Linux is as follows:

/etc/apache2/sites-available/example:

<VirtualHost *:443>
        ServerAdmin admin@example.com
        ServerName intranet.example.com

        DocumentRoot /var/www/intranet/
        <Directory />
                Options FollowSymLinks
                AllowOverride None
        </Directory>
        <Directory /var/www/intranet/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride All
                Order allow,deny
                allow from all
        </Directory>

        <Location /user/login/sso>
                AuthType Kerberos
                KrbAuthRealms EXAMPLE.COM
                KrbServiceName HTTP/intranet.example.com@EXAMPLE.COM
                Krb5Keytab /etc/apache2/kerbintranet.keytab
                KrbMethodNegotiate on
                KrbMethodK5Passwd off
                require valid-user
        </Location>

        ErrorLog ${APACHE_LOG_DIR}/error-intranet.log

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog ${APACHE_LOG_DIR}/access-intranet.log combined
</VirtualHost>

Further details on Kerberos on the Ubuntu: