Configuring Apache Web Server for x509 User Authentication

Table of Contents

1. Introduction
2. Scenario
3. Configuring Active Directory
4. Configuring Apache

Chapter 1. Introduction

This document describes the method of configuring Apache web server for x509 user authentication using MS Active Directory server as a LDAP server for retrieving user information.

The DSO modules mod_authz_ldap and mod_ssl for Apache are used for x509 certificate verification and user mapping. MS Active Directory is used as a LDAP server for retrieving user information (user mapping).

Chapter 2. Scenario

A client wants to access to our web application. He already has his own x509 certificate installed in his browser. Apache web server tries to authenticate the client using mod_ssl and the client’s x509 certificate (public key). Apache (mod_ssl) is configured to know where to look for user certificates. The certificates are stored in a directory on the web server.

After successful user authentication Apache has, as the result of authentication, two parameters: issuerDN and subjectDN. Further, the client requests should be forward to the appropriate application server that uses basic authentication system. That means we have to know the client’s user name and password. It is necessary to map issuerDN and subjectDN to user name and password. Apache uses mod_authz_ldap DSO to perform such a mapping. Mod_authz_ldap, using issuerDN and subjectDN, retrieves username and password from LDAP server. LDAP server contains the map between issuerDN, subjectDN and username, password pairs. MS Active Directory acts as an LDAPv3 server.

Than mod_authz_ldap overwrites client’s HTTP request in a way client could be authenticate by the application server using basic authentication.

Chapter 3. Configuring Active Directory

In order to store the user map in Active Directory (LDAP server) it is needed to add a LDAP schema that represents the map between subjectDN, issuerDN and username, password pairs. It needs to contain the following types:

objectClasses: ( NAME 'authzLDAPmap' SUP top
STRUCTURAL MUST ( issuerDN $ owner $ subjectDN $ uid ) X-ORIGIN 'user defined' )

attributeTypes: ( NAME 'issuerDN' DESC 'The user
friendly version of the distinguished name of the issuer of a
certificate' SYNTAX SINGLE-VALUE X-ORIGIN 'user defined' )

attributeTypes: ( NAME 'subjectDN' DESC 'The user
friendly version of the distinguished name of the subject of a
certificate' SYNTAX SINGLE-VALUE X-ORIGIN 'user defined' )

To extend Active Directory schema it could be used MMC (Microsoft management console) schmmgmt. Detail explanation of extending schema could be found here:

After the schema is extended and objectClass authzLDAPmap is added we have to import actual data in to the LDAP server. It is needed to add data entries like the following (in LDIF format):

dn: ou=AuthzLDAPCertmap
objectClass: top
objectClass: organizationalUnit

dn: uid=username,ou=AuthzLDAPCertmap
owner: uid=username,ou=Users
objectClass: top
objectClass: authzLDAPmap
issuerDN: <issuerDN>
subjectDN: <subjectDN>
uid: username


In this example it is assumed that user entries are located in an organizational unit Users (ou=users).

For adding entries into ActiveDirectory, LDP (ldp.exe, the Microsoft ldap client) could be used. LDP utility is included in Windows Servers Resource Toolkit.

Chapter 4. Configuring Apache

Detail explanation of using mod_authz_module (with examples) could be found here

In the first place we have to add these two lines in order to load module mod_authz_ldap:

LoadModule authz_ldap_module   libexec/
AddModule mod_authz_ldap.c

Than we have to add in to the httpd.conf the following section:

SSLCertificateFile <path to the crt file>
SSLCertificateKeyFile <path to the key file>
SSLEngine on
<Location /somelocation>
     AuthzLDAPEngine on
     AuthzLDAPServer <active directory server>
     AuthzLDAPUseCertificate on
     AuthzLDAPSetAuthorization off
     AuthzLDAPMapBase ou=AuthzLDAPCertmap
     AuthzLDAPMapScope subtree
     AuthzLDAPUserKey   sAMAccountName
     AuthzLDAPUserBase  ou=Users
     AuthzLDAPUserScope subtree
     AuthzLDAPBindDN  username@domain
     AuthzLDAPBindPassword userpassword

     require valid-user

Information about generating user certificates and how-to install them could be found here: