mod_auth

Introduction

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>