== OpenLDAP Practical 2, Week 7 ==

This practical is about configuring Apache so that it uses our OpenLDAP
directory to accept or deny HTTP authentication requests.

At the end of the practical, we should be able to add or remove users that are
allowed to authenticate on the website by adding or removing LDAP entries.

=== Problem 1: Avoiding obsolete commands ===

The practical provides us some commands to, inter alia, configure Apache.
Nevertheless some of them are obsolete or deprecated. Here is a list of
obsolete ways and their prefered substitute:

- enabling an Apache module by creating symlinks by hand. The recommended way
  is to use the command 'a2enmod' which takes the name of the module (i.e.
without file extension) and generate the symlink(s) to the proper file(s)
itself. In our case, the command is:

    $ sudo a2enmod ldap

- stopping, starting (that to say restarting) a service (i.e. Apache) on
  Debian-like distributions can be achieved by using the command 'service'. In
addition to avoiding any risk of messing up anything inside the '/etc/init.d/'
directory, this tool first checks in '/etc/init' if there is an upstart job of
the same name. In our case, the command for restarting Apache is:

    $ sudo service apache2 restart

- enabling an Apache site can be achieved using the command 'a2ensite' which is
  very similar to 'a2enmod'. The advantage of this method is that it avoids the
risk of messing up with the precedence of the configuration files when enabling
multiple sites.

=== Problem 2: Enabling the LDAP authentication module ===

After having a look at the documentation of 'mod_auth_ldap' (provided in the
'Supporting Information' section of the practical), we try to activate the
module with the command below but we are indeed facing an error:

    $ sudo a2enmod auth_ldap
    > ERROR: Module auth_ldap does not exist!

==== Resolution ====

The answer is actually somehow given at the very beginning of the documentation
of 'mod_auth_ldap':

[verse]
This document refers to the 2.0 version of Apache httpd, which is no longer maintained. Upgrade, and refer to the current version of httpd instead, documented at [...]

Following the given link and browsing to 'Authentication and Authorization'
suggests us another module (that we luckily have): 'mod_authnz_ldap' which we
can successfully activate by issuing the following command and then restarting Apache.

    $ sudo a2enmod authnz_ldap

=== Problem 3: Configuring the authentication mechanism ===

After configuring Apache so that the authentication can be overriden in
'.htaccess' files (similarly to what we did in Apache Practical), we have to
figure out what directives to write in our '.htaccess' file to handle HTTP
authentication using LDAP.

The documentation of 'mod_authnz_ldap' covers almost every information we need.
Since we think that allowing only the users whose 'permisRole' is set to
'staff' to access the website, we construct our '.htaccess' file this way:

    AuthBasicProvider ldap
    AuthLDAPURL "ldap://localhost/ou=MSc ISB,o=University of Kent,c=gb?uid?one"
    Require ldap-attribute permisRole=staff

Nevertheless, when we try to access the website, we get an 'Internal Server
Error'.

==== Resolution ====

To understand what is going wrong, we can read the end of the file
'/var/log/apache2/error.log'. More preferably, we can run the following command
on another terminal (or as a background process) so that we will be informed of
any other error that we will encounter afterwards:

    $ tail -f /var/log/apache2/error.log
    > configuration error:  couldn't perform authentication. AuthType not set!: /

The output is rather clear, we need to add the authentication type (which is
still 'Basic' in our case).

After another attempt with another 'Internal Server Error', our 'tail' running
process gives us this output

    > need AuthName: /

The output is once again rather clear, we just have to add a authentication
name of our choice.

After those modifications, our '.htaccess' looks something like this:

    AuthType Basic
    AuthName "You need to authenticate with a LDAP entry"
    AuthBasicProvider ldap
    AuthLDAPURL "ldap://localhost/ou=MSc ISB,o=University of Kent,c=gb?uid?one"
    Require ldap-attribute permisRole=staff

=== Problem 4: Testing our authentication ===

We still need to test our authentication to validate its proper functioning.
For that purpose, we have to add at least another entry in the LDAP directory
and run some tests using 'curl'.

==== Resolution ====

First, we will add another user (whose 'permisRole' is 'staff'). The input that
we have to provide to 'ldapadd' is the following:

    dn: cn=Olivier Gayot Staff,ou=MSc ISB,o=University of Kent,c=gb
    objectClass: organizationalPerson
    objectClass: pkiUser
    objectClass: pmiUser
    objectClass: uidObject
    sn: gayot
    uid: ojgg
    userPassword: fooBar
    permisRole: staff

Using 'curl' the same way we did in the Apache practical, we can run some tests (only interesting excerpts of the output are shown below):

.trying (with success) to authenticate using the staff account
======

    $ curl http://csvm2c4e.kent.ac.uk -u 'ojgg:fooBar'
    > <h1>It works!</h1>

======

.trying (without success) to authenticate using the student account
======

    $ curl http://csvm2c4e.kent.ac.uk -u 'ojgg2:fooBar'
    > <title>401 Authorization Required</title>

======

.trying (without success) to authenticate with a wrong password
======

    $ curl http://csvm2c4e.kent.ac.uk -u 'ojgg:wrongPassword'
    > <title>401 Authorization Required</title>

In the meanwhile our 'tail' process gives us:

    > user ojgg: authentication failure for "/": Password Mismatch

======