use *.asciidoc(i) extension instead of *.adoc(i)

Signed-off-by: Olivier Gayot <duskcoder@gmail.com>

1 files changed, 156 insertions, 0 deletions

diff --git a/ldap2.asciidoci b/ldap2.asciidoci
new file mode 100644
index 0000000..76ee056
--- /dev/null
+++ b/ldap2.asciidoci
@@ -0,0 +1,156 @@
+== 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 (which we 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
+
+======
+