Read Me

Introduction
------------
"mod_auth_certificate" is an authentication module for the Apache 2.x server. 
It adds the capability to forward usernames returned by mod_ssl to authorization
modules or providers as the are called since >= 2.2.x.

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

1. Compile and install the module using apxs (APache eXtenSion tool):
     $ /path/to/apache/bin/apxs -c -i mod_auth_certificate.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)

   If ld complains about wrong output format, use "-Wl,-m32" as parameter for
   apxs.
 
2. Instruct apache to load the module by adding

      LoadModule auth_certificate_module   libexec/mod_auth_certificate.so

   to the appropriate place in your httpd.conf


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

The module supports the following per Directory/Location directive:

CertAuthEnabled
  Set to 'on' to use certificate authentication with mod_auth_certificate.

The module will always be authoritative if "AuthType Cert" is
configured. If you want to have fallback to mod_auth_basic or mod_auth_digest
configure "AuthType Basic" or "AuthType Digest".


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

  SSLEngine on
  SSLCACertificateFile ...

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

  SSLVerify 10

  # Configure SSL Variable to username mapping
  SSLUserName SSL_CLIENT_S_DN_CN

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


Examples
--------

<Location />
  AuthCertEnabled on

  AuthType Cert

  require valid-user
</Location>

---

# Combine certificate based authentication with authorization
# from mod_authz_groupfile
<Location />
  AuthCertEnabled on

  AuthType Cert

  AuthGroupFile conf/mygroups
  require group admin
</Location>

---

# Use certificate based authentication if possible or fallback to
# basic authentication
<Location />
  AuthCertEnabled on

  AuthType Basic
  AuthName "My Realm"
  AuthBasicProvider file
  AuthUserFile conf/myusers

  AuthGroupFile conf/mygroups
  require group admin
</Location>


Changelog
---------

v0.2 06/19/2009:
* Relicensed under Apache License 2.0
* Code cleanup

v0.1 06/10/2009:
* Initial release