Enabling Authentication in Apache

In order to integrate the Apache web server with Active Directory authentication, you will need to reconfigure the settings associated with the virtual directory used by the Watson Explorer Engine. The Apache settings for this directory are stored in the file vivisimo-apache.conf in your Watson Explorer Engine installation directory.

When you first install the Watson Explorer Engine, the vivisimo-apache.conf file should look something like the following if you accept the default values during the installation process:

      ScriptAlias "/vivisimo//cgi-bin/" "/opt/ibm/WEX/Engine/www/cgi-bin/"
      Alias "/vivisimo//images/" "/opt/ibm/WEX/Engine/www/images/"
      Alias "/vivisimo//js/" "/opt/ibm/WEX/Engine/www/js/"
      Alias "/vivisimo//" "/opt/ibm/WEX/Engine/www/en/"

      <Directory "/opt/ibm/WEX/Engine">
         SetEnv LD_LIBRARY_PATH "/opt/ibm/WEX/Engine/lib/:"
      </Directory>

To integrate Active Directory authentication with the directory where your Watson Explorer Engine software was installed (which was /opt/ibm/WEX/Engine in this example), you will need to change this file, substantially increasing the size of the Directory stanza for /opt/ibm/WEX/Engine so that it looks something like one of the following two examples.

If you are running Apache 2.1.x or earlier and your web server process is still named httpd, you will need to make modifications like the following to your vivisimo-apache.conf file:

      ScriptAlias "/vivisimo//cgi-bin/" "/opt/ibm/WEX/Engine/www/cgi-bin/"
      Alias "/vivisimo//images/" "/opt/ibm/WEX/Engine/www/images/"
      Alias "/vivisimo//js/" "/opt/ibm/WEX/Engine/www/js/"
      Alias "/vivisimo//" "/opt/ibm/WEX/Engine/www/en/"

      LoadModule ldap_module /etc/httpd/modules/mod_ldap.so
      LoadModule auth_ldap_module /etc/httpd/modules/mod_auth_ldap.so

      <Directory "/opt/ibm/WEX/Engine">
        <Files "crawler-test">
          AddDefaultCharset Off
        </Files>

        Options All ExecCGI -Indexes

        Order allow,deny
        Allow from all

        AuthType Basic
        AuthName "Training Domain"
        AuthLDAPAuthoritative On

        AuthLDAPURL "ldap://192.168.0.66:389/CN=Users,DC=training,DC=local\
        ?sAMAccountName?sub?(objectClass=*)"
        AuthLDAPBindDN CN=Administrator,CN=Users,DC=training,DC=local
        AuthLDAPBindPassword password

        Require valid-user

      </Directory>

Note: The backslash and following newline in the value of the AuthLDAPURL variable in this example must not be present in your Apache configuration file. They are shown here for formatting purposes. This value should be a single string.

If you are running Apache 2.2.x or greater and your web server process is named apache2, you will need to make modifications like the following to your vivisimo-apache.conf file:

      ScriptAlias "/vivisimo//cgi-bin/" "/opt/ibm/WEX/Engine/www/cgi-bin/"
      Alias "/vivisimo//images/" "/opt/ibm/WEX/Engine/www/images/"
      Alias "/vivisimo//js/" "/opt/ibm/WEX/Engine/www/js/"
      Alias "/vivisimo//" "/opt/ibm/WEX/Engine/www/en/"

      LoadModule ldap_module /usr/lib/apache2/modules/mod_ldap.so
      LoadModule authnz_ldap_module /usr/lib/apache2/modules/mod_authnz_ldap.so

      <Directory "/opt/ibm/WEX/Engine">
        SetEnv LD_LIBRARY_PATH "/opt/ibm/WEX/Engine/lib/"

        Options All ExecCGI -Indexes

        Order allow,deny
        Allow from all

        AuthType Basic
        AuthBasicProvider ldap
        AuthName "Training Domain"
        AuthzLDAPAuthoritative Off

        AuthLDAPURL "ldap://192.168.0.66:389/CN=Users,DC=training,DC=local\
        ?sAMAccountName?sub?(objectClass=*)"
        AuthLDAPBindDN CN=Administrator,CN=Users,DC=training,DC=local
        AuthLDAPBindPassword password

        Require valid-user

      </Directory>

As you can see, these examples are very similar. The primary differences are the path and file names of the LDAP-related modules, whether the AuthBasicProvider directive is required (or valid), and the value for the AuthzLDAPAuthoritative directive. These are explained in the following list of LDAP-related changes to your web server's configuration file.

The new entries added to this file have the following meanings:

Loadmodule - these commands load modules into the Apache framework that handle connecting to an LDAP authentication source and getting authentication information, and applying that LDAP authorization data to the data that you retrieve from the Web server. Older Apache distributions use the auth_ldap_module instead of the authnz_ldap_module. These modules function almost identically, the primary difference being that if you are using the auth_ldap_module module, you will need to use the AuthLDAPAuthoritative directive instead of the AuthzLDAPAuthoritative directive later in this stanza.
Note: If these modules are already loaded into your web server, you do not need to specify them again. See your web server system administrator.
Options - enables the execution of CGI scripts from within this directory and prevent an index (essentially a directory listing) of this directory from being displayed.
Order and Allow - specifies the order in which any allow and deny statements used to enable or restrict directory access, will be evaluated. In this case, the Order statement says that everyone will be allowed access to the site unless explicitly denied access, and the Allow statement explicitly allows access to this directory from everywhere.
AuthType - tells Apache to use standard username/password authentication. This sends the password in the clear, and therefore is typically used with SSL or only on secure or internal networks.
AuthBasicProvider - tells Apache the mechanism to use for resolving usernames and passwords. The default value is file, which uses a password file, so you must specify ldap to tell the web server that it should expect to resolve these requests against an LDAP/Active Directory server. This value is only necessary if your web server is Apache 2.1.x or later.
AuthName - provides a string that is displayed in the login/password dialog to help users identify which authentication daemon is prompting them for information, and therefore which username/password combination to supply.
AuthzLDAPAuthoritative - tells Apache not to consult other authentication sources after contacting the LDAP server (On) or to proceed with any other authentication necessary (Off). This must be set to off when using the require valid-user directive with LDAP and the authnz_ldap_module module. This option should be set to On for versions of Apache prior to 2.1, and to Off for later versions of Apache.
AuthLDAPURL - the URL for the LDAP or Active Directory server that you want to contact. Port 389 is the default LDAP port. The CN (common name) and DC (domain component) entries are used to identify the path in the LDAP hierarchy that you want to query for authentication information using the sAMAccountName?sub?(ObjectClass=*) query.
AuthLDAPBindDN - the LDAP identifier for a user who has sufficient privileges to read data from LDAP.
AuthLDAPBindPassword - the password for the user specified by the AuthLDAPBindDN keyword.
require - identifies the authentication requirement for accessing this directory. In this case, require valid-user means that you must successfully authenticate to LDAP in order to access the web server's virtual vivisimo directory.

At this point, you should restart your apache server, usually by using whichever of the following utilities is appropriate for your system:

/etc/init.d/apache2 graceful
apache2ctl graceful
/etc/init.d/httpd graceful
apachectl graceful

The graceful keyword restarts the Apache daemon without closing open connections.

After restarting Apache, attempting to execute the Watson Explorer Engine administration tool should display a username and password dialog, in which you can successfully authenticate.

To proceed with this tutorial and learn how to enable authentication in the Microsoft IIS web server, click Enabling Authentication in IIS. To learn how to enable authentication in your project, click Customizing Search Application Authentication Settings.