Introduction
------------
"mod_auth_cert" is an authentication module for the Apache 1.3.x/2.x server. 
It can be used to map the Subject DN of a X509 client certificate to a username. 
The module can be combined with other authentication modules.

Installation
------------

1. Compile and install the module using apxs (APache eXtenSion tool):
     $ /path/to/apache/bin/apxs -c -i mod_auth_cert.c

   If apxs complains about missing openssl headers, pass the path to those
   headers using apxs's -I option (e.g. apxs -I /usr/include/openssl)
 
2. Instruct apache to load the module by adding

      LoadModule cert_auth_module   libexec/mod_auth_cert.so
      AddModule mod_auth_cert.c   # Not required with Apache 2.x

   to the appropriate place in your httpd.conf


Configuration
-------------

The module uses a textfile to map Subject DNs to usernames. The map file
may consist of multiple lines in the following format:

  username:subject dn

e.g:

jdoe:/C=ORG/ST=XY/L=Smallville/O=Foo Org./CN=John Doe/emailAddress=john.doe@foo.org
fbar:/C=ORG/ST=XY/L=Smallville/O=Foo Org./CN=Foo Bar/emailAddress=foo.bar@foo.org

The module supports the following per Directory/Location directives:

CertAuthMapFile
  Text file containing user ID to Subject DN mappings

CertAuthAuthoritative
  Set to 'off' to allow access control to be passed along to lower modules if
  the UserID is not known to this module

CertAuthSetAuthorization
  Set to 'off' if this module should not set a authorization header.

For this module to work, you have to instruct mod_ssl to require Client
Certificates:

  SSLEngine on
  SSLCACertificateFile ...

  # When combining mod_auth_cert with basic authentication use "optional"
  # instead of "require"
  SSLVerifyClient require

  SSLVerify 10

Have a look at the mod_ssl documentation for more information about these
directives.


Examples
--------

<Location />
  AuthType cert
  CertAuthMapFile conf/certmap
  require valid-user
</Location>

---

# Combine certificate based authentication with authorization
# from mod_auth
<Location />
  AuthType cert
  CertAuthMapFile conf/certmap
  AuthGroupFile   conf/mygroups
  require group admin
</Location>

---

# Use certificate based authentication if possible or fallback to
# basic authentication
<Location />
  AuthType basic
  AuthName "My Realm"
  CertAuthAuthoritative off
  CertAuthMapFile conf/certmap
  AuthGroupFile   conf/mygroups
  AuthUserFile    conf/myusers
  require group admin
</Location>


Changelog
---------

v0.3 08/09/2007:
* Support for Apache 2.2.x

v0.2 02/13/2006:
* Support for Apache 2.0.x

v0.1 03/31/2003:
* Initial release
