How-To Docs

• Home
• How-to
• mod_auth_pam
  • Discussion forum

• Home >
• How-to >
• mod_auth_pam

Using VAS and mod_auth_pam to authenticate Apache users

• About mod_auth_pam
• Comparing mod_auth_pam with standard Apache authentication
• The file-based way of authenticating users
• The PAM way of authenticating users
• Building, installing and configuring mod_auth_pam with VAS
• Configuring mod_auth_pam with .htaccess
• Troubleshooting tips
• SELinux restricts Apache by default
• Getting a "no groups file" error from Apache 2
• How to enable logging to track down problems

About mod_auth_pam

mod_auth_pam is a free Apache authentication module that implements Basic authentication on top of the Pluggable Authentication Module (PAM) library. Using mod_auth_pam allows users to authenticate through their web browser using a login and password that can be checked by a system PAM module.

This page documents how mod_auth_pam can be configured to use the Vintela Authentication Service (VAS) PAM module. This permits integration of Unix web server authentication with Active Directory user management.

The VAS PAM module (pam_vas) is supplied as part of Vintela Authentication Services (VAS), and the PAM module for Apache (mod_auth_pam) can be downloaded from pam.sourceforge.net.

Note: Because mod_auth_pam only implements Basic HTTP authentication (which prompts the user) it is not true single sign-on. If you are looking for single sign-on authentication functionality, you'll probably be more interested in the mod_auth_vas project. In addition, because Basic authentication effectively sends passwords in the clear across the network, you will need to enable HTTPS (SSL) on your web server.

Comparing mod_auth_pam with standard Apache authentication

In certain web applications, it is desirable to use system user accounts for web site authentication—instead of the separate .htpasswd files that people typically use—in order to restrict access to web content on the widely-deployed Apache web server. This document explains how you can implement this type of authentication in a VAS/Active Directory environment. This can greatly simplify the administration of web-access restriction in an environment where Active Directory is already managing the users.

We can do this using the mod_auth_pam Apache extension. Because of the way VAS integrates with the native PAM (Pluggable Authentication Module) and NSS (Name Service Switch) interfaces of Unix and Linux systems, integrating the mod_auth_pam-enabled Apache server with Active Directory requires very little configuration.

The file-based way of authenticating users

Before describing how mod_auth_pam works, it is worth looking briefly at the standard auth module, and how it works.

Apache provides a robust extension mechanism to let module developers implement new and extended functionality. The internal Apache APIs (application programming interfaces) allow developers to integrate external functionality into the server. One of the internal Apache APIs is the Apache's authentication framework. One standard module, auth, uses this framwork to provide Apache's built-in, simple authentication scheme. The auth module uses the authentication framework to restrict web client access to web server content on a per-directory basis. In order to restrict a certain directory, say /resources, to just the members of the Unix group webusers and the user admin, place an .htaccess configuration file in the /resources directory, with the following content:

AuthType Basic
AuthName "Restricted Resources"

AuthUserFile /srv/www/passwd/resources/.htpasswd
AuthGroupFile /srv/www/passwd/resources/.htgroup
Require group webusers

Require user admin

A brief outline follows, but full documentation on the directives can be found at the Apache 2.0 and Apache 1.3 online documentation.

The AuthUserFile (and AuthGroupFile) directives take a file pathname as a parameter. This pathname points to a file, which contains the username and passwords in an encrypted form. Apache challenges the web user for a password, encrypts the password and checks the encrypted form against the encrypted password in the file. It grants users access to this directory only when they match. The htpasswd utility is used to create and change entries in the password file.

The problem with this approach is that the htpasswd file incurs the administrative overheads of creation, maintennance and synchronization, and/or management of forgotten passwords.

The PAM way of authenticating users

Using mod_auth_pam provides an alternative authentication scheme that uses PAM to authenticate web users and groups against system users. You do not use an .htaccess file, or the AuthUserFile and AuthGroupFile directives because Apache sends the received password directly to the mod_auth_pam module, which passes it to PAM, which then passes it to VAS, which finally passes it to Active Directory. Active Directory checks it against the centrally stored passwords, and the permit/deny result is returned back to Apache.

The upshot is that this eliminates the overhead of separate creation, maintenance, and synchronization of the password files required by the standard Apache authentication (mod_auth). If the web applications being served are for a user population that is already being managed with Active Directory, this solution allows organizations to easily provide a single user name and password for Windows desktops, UNIX and Linux logins, and for restricted web content or applications, with no ongoing password file maintenance outside of Active Directory.

Building, installing and configuring mod_auth_pam with VAS

mod_auth_pam is an open source project, distributed at http://pam.sourceforge.net/mod_auth_pam/. It is provided in two versions, one for Apache 1.3 and one Apache 2.0. They are both provided as tar files rather than platform-specific packages.

They are simple modules, however, and building and installing them is straightforward. The sourceforge site provides installation and configuration notes, although they are quite terse. As a real-world example, this article steps through the process of building, installing, and configuring the module as a DSO (Dynamic Shared Object) for the SuSE Linux 9.0 platform. Apache modules are typically built as a DSO, provided that the initial Apache build was compiled to support them. This example illustrates some of the issues you may encounter in building the module for a specific target.

Once you have downloaded and unpacked the sources into a working directory, make sure that the requisite library and header files are installed that support both Apache and PAM development. On the SuSE Linux distribution, for example, these are in the apache2-devel and pamdevel RPM packages. The Apache headers are also available as part of the Apache source distribution, if you have built Apache from source.

In our example case, working with the Apache 2.0 build, there is one change you must make to the Makefile. The file as distributed has the definition APXS=apxs. apxs is a build utility included with the Apache distribution for linking and installing Apache modules as a DSO. Since the Apache 2.0 apxs is different from the Apache 1.3 apxs, the SuSE Linux people renamed the apxs in version 2.0 to apxs2. So you must change this line to read APXS=apxs2. This is the only change you need to make to the Makefile.

You are now ready to follow the instructions provided on the project site:

1. cd to the directory where you unpacked the sources:

   $ cd some-directory

2. Build and install the module:

   $ make
   $ make install

3. Apply configuration changes for PAM
4. Restart Apache:

   # sh /etc/init.d/apache2 restart

   (The control script may also be called httpd or apache depending on the flavour of Linux)

Before you restart Apache, you may need to make a few more configuration changes for the default SuSE environment, which may possibly apply to your platform as well. The mod_auth_pam FAQ describe these configuration details, along with others. However, the first is to allow per-directory configuration of authentication/authorization as the default Apache httpd.conf files usually does not allow this.

If there is an AllowOverride None directive in the <Directory> section of httpd.conf, replace it with AllowOverride AuthConfig.

The other consideration encountered with the SuSE installation is actually not an issue if you are only planning to authenticate users by means of VAS. However, if you wish to use (or simply test) the mod_auth_pam module with local accounts, and if shadow passwords are in effect (as is the default case of the SuSE install), you need to configure Apache properly. The web server process needs to access the /etc/shadow file in order for mod_auth_pam to work with local accounts. In this example, the /etc/shadow file belonged to the shadow group. If you add the directive Group shadow to the httpd.conf file, you will enable it to access the shadow password file. Please read about the security implications of this: you only need to make this configuration step if you want to enable the use of local passwords on a shadow password system.

At this point, you should restart Apache and test accessing the web server with local account passwords.

Next, we configure VAS/PAM to play nicely with Apache. Apache makes itself known to PAM with the service name httpd. The make install command usually configures an httpd service entry in the /etc/pam.d directory. You will need to modify this file to make it use VAS. (This step is always needed, regardless of platform.)

The easiest way to make the modifications is to use this command:

# /opt/vintela/vas/bin/vastool configure pam httpd

Afterwards, if you wish to only allow authentication of web pages through VAS and Active Directory, remove the auth and account entries that reference the /etc/pam.d/httpd file, once you configure the httpd service. This will disable authentication against the local passwd file. Leave only the VAS configuration entries. In this case, the previously discussed Group shadow modification to the httpd.conf files mentioned above is unnecessary.

At this point, PAM/VAS should be fully operational. PAM dynamically checks its configuration files, so there is no need to restart the Apache server.

You can perform a further configuration optimization on the httpd service configuration file in /etc/pam.d. You can remove the get_tgt and create_homediroptions from the pam_vas.so command on the auth entry line because you are only using the mod_auth_pam module for web application authentication. This enhances performance by disabling the acquisition of a Kerberos credential, as well as to skip the creation of a user home directory on the web server host. See the pam_vas manual page on your system to see full documentation on these and other features.

Configuring mod_auth_pam with .htaccess

You can configure mod_auth_pam on a per-directory basis as explained previously, except that you do not use the AuthUserFile directive. Your .htaccess file might look like the following:

AuthType Basic
AuthName "Restricted Resources"
Require group webusers
Require user admin

That example allows members of the group webusers or the user admin to access contents of the directory containing the .htaccess file. With this configuration, Apache uses mod_auth_pam and VAS to authenticate users and groups against Active Directory. In order to decide access use the Require group directive with a group name that is defined (and UNIX-enabled) in Active Directory specifically to contain those users authorized to access the pages in question. If you make a change in group membership (for example, in webusers) the changes will automatically propagate from Active Directory to the web content or application, without having to modify anything on the Apache server. Although you may specify individual users in a Require directive, this is less useful as it defeats the ability to manage access entirely from Active Directory.

Troubleshooting tips

SELinux restricts Apache by default

On systems where SELinux is installed and enabled, the web server is usually given restricted privileges. This shows up as entries in /var/log/messages like this:

Jun 21 21:52:50 fc3 kernel: audit(1119354770.758:0): avc:  
	     denied  { read } for  pid=8534 exe=/usr/sbin/httpd 
	     name=misc.vdb dev=dm-0 ino=406694 scontext=root:system_r:httpd_t 
	     tcontext=system_u:object_r:var_t tclass=file

To fix this, you will either need to disable selinux, or modify the selinux policy and file contexts for the files concerned.

See also:

• The RHEL4 SELinux Guide
• Understanding and Customizing the Apache HTTP SELinux Policy
• Sourceforge SELinux HOWTOs
• SELinux NSA's Open Source Security Enhanced Linux by Bill McCarty
• Configuring the SELinux Policy,

Getting a "no groups file" error from Apache 2

(Atul Patel, Jan 2004)

If you are getting a "No groups file" error and using Apache 2, make sure the following is correct:

1. You modified mod_auth_pam's Makefile line to read

   APXS=/usr/sbin/apxs2

2. The following two lines can be found in the httpd.conf file:

   LoadModule auth_pam_module modules/mod_auth_pam.so
   LoadModule auth_sys_group_module modules/mod_auth_sys_group.so

How to enable logging to track down problems

Here are a few pointers on how to enable debug mode for the pam_vas module:

1. You'll need to locate your platform specific pam.conf file. On Red Hat it's generally /etc/pam.d/system-auth and on Solaris it's /etc/pam.conf.

   In this file you'll find the PAM configuration for the pam_vas module. There should be several lines that look like this:

   auth [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so \
   	get_tgt create_homedir
   account [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so
   password [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so
   session [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so

   You'll want to add the options debug and trace to the end of the lines. Just add those specific words to the end of the appropriate line(s), like so:

   auth [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so \
   	get_tgt create_homedir debug trace
   account [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so debug trace
   password [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so debug trace
   session [ignore=ignore success=done default=die] /opt/vas/lib/security/pam_vas.so debug trace

2. Once this is done you'll want to make sure your system logger is logging debug and auth messages somewhere. For example, you'll want to add *.debug and authpriv.* entries to /etc/syslog.conf on Linux:

   *.debug,authpriv.*       /var/log/mydebug

   You can log to an existing log file or create a separate one to keep things clutter free. See the man page on syslog.conf for more details. Use this command to continuously watch the output:

   # tail -f /var/log/mydebug

3. Restart sylogd

   # /etc/init.d/syslog restart

After you have configured syslog to record the log messages somewhere, you should retry your attempts with sudo or apache 2 and see if any additional details are being logged.

You may also want to list the AD groups to verify that the group you have setup in AD and Unix-enabled is being seen by VAS. Use this command:

$ /opt/vintela/vas/bin/vastool list groups

Last modified: Thu, 23 Aug 2007 23:13:01 -0600
© 2007 Quest Software, Inc. All rights reserved. | Terms of use