5. Tying it all together

In this section, I'll give a simple example which ought to help tie together what's in the previous section.

5.1. Apache + mod_auth_pam

As our example, we'll install and configure mod_auth_pam, an Apache module that allows you to authenticate users of your webserver using PAM. For the purpose of this example, I'll assume you have apache installed. If it's not installed already you should be able find installation packages from your distributor.

5.2. Our example

Our goal will be to configure a restricted area of our webserver, a family/ directory, to authenticate users via PAM. This directory contains private family information, and should only be accessible to members of the user group family.

5.3. Installing mod_auth_pam

First, you'll want to download mod_auth_pam from http://blank.pages.de/pam/mod_auth_pam/. The following commands will compile mod_auth_pam (you must be logged in as root):

   ~# tar xzf mod_auth_pam.tar.gz
   ~# cd mod_auth_pam-1.0a
   ~/mod_auth_pam-1.0a# make
   ~/mod_auth_pam-1.0a# make install

If you have any trouble installing the mod_auth_pam module, make sure you've installed your distribution's apache-dev package. After you've installed mod_auth_pam, you'll need to restart apache. Apache can usually by restarted by typing the following command (again, you must be root):

   ~# /etc/init.d/apache restart

5.4. Configuring PAM

The PAM configuration for Apache is stored in /etc/pam.d/httpd. The default configuration (which was installed when you installed mod_auth_pam) is secure, but it uses a module (pam_pwdb.so) which may not be available on many systems. (Besides, configuring it from scratch will be fun!) So delete the /etc/pam.d/httpd file, and start with a fresh one.

5.4.1. Deciding how to configure PAM

If we're going to configure how PAM deals with Apache's authentication requests, we need to figure out exactly what we need PAM to check for. First, we want PAM to make sure the user's password matches their password in the standard unix password database. This sounds like the 'auth' type and the pam_unix.so module. We'll want the module's control type to be set to 'required', so authentication will fail without a correct password. Here's what the first line of our /etc/pam.d/httpd looks like:

     auth	required	pam_unix.so

Secondly, we must make sure that the users account is valid (i.e. their password has not expired or any such nastiness). This is the 'account' type and is also provided by the pam_unix.so module. Again, we'll set this module's control type to 'required'. After adding this line, our /etc/pam.d/httpd configuration looks like this:

     auth	required	pam_unix.so
     account	required	pam_unix.so

It's not terribly sophisticated, but it does the job. It ought to be a good start for learning how to configure PAM services.

5.5. Configuring Apache

Now that PAM is configured to authenticate apache's requests, we'll configure apache to properly utilize PAM authentication to restrict access to the family/ directory. To do so, add the following lines to your httpd.conf (usually stored in /etc/apache/ or /etc/httpd):

    <Directory /var/www/family>
    AuthPAM_Enabled on
    AllowOverride None
    AuthName "Family Secrets"
    AuthType "basic"
    require group family
    </Directory>

You may need to replace /var/www/ with the default location of web documents, which is often /home/httpd/. Wherever that is, you'll need to create the family directory.

Before we test our setup, I'll take a moment to explain the Apache configuration you just entered. The <Directory> directive is used to encapsulate configuration data for this directory. Inside this directive, we've enabled PAM authentication ("AuthPAM_enabled on"), turned off any overriding of this configuration ("AllowOverride none"), named this authentication zone "Family Secrets" ("AuthName "Family Secrets""), set the http authentication (not the PAM authentication) type to the default ("AuthType "basic""), and required the user group family ("require group family").

5.6. Testing our setup

Now that we've got everything setup up properly, it's time to revel in our success. Fire up your favorite web browser and head over to http://your-domain/family/ (replacing your-domain with, well, your domain). You are now an uber-authenticator!

HOWTOs