Introduction

SourceForge.net Logo
mod_auth_cert is an Apache 1.3.x/2.0.x module that 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.

Download

The source code of mod_auth_cert is available at this location.

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, add the path to the headers using apxs'es -I option

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 for Apache 2.0
to the appropriate places 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.

Configuration examples

# Map client certificate to username, if user has no client certificate
# or no mapping exists, the web server will return HTTP_FORBIDDEN
<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>