6.0.0-git
2018-12-17
Last Modified 2013-08-28 by Michael Rubinsky

The question came up: "What needs to be modified in order to provide Horde authentication using X509 digital certificates?"

PKI

Obviously, one will need user certificates and a means to distribute them; a description of setting up a Public Key Infrastructure is beyond this document. You should make yourself comfortable with PKI concepts before diving in. If you don't know what a PKI is and the relationship between keys, certificates, and a CA, you will find yourself in deep water fairly quickly. Not trying to be snarky here, but it will pay to do your homework; you might start at the Wikipedia PKI entry.

Horde Auth

Authenticating to Horde should be surprisingly simple, and you should be able to use the Basic Authentication driver, since Apache's X509 authentication functions in much the same manner and relies on the web server prompting one's browser to authenticate.

But Wait!

Authenticating using X509 user certificates has more in common with using the Shibboleth Authentication Driver. For example, unlike real Basic Authentication, one's password is never passed across the network, and is not available in an environment variable. Unless you plan on using X509 authentication for your mail service (most unlikely), you should pay close attention to faking a SSO (Single Sign On) arrangement. Specifically, you should examine the instructions and samples there for

  • selecting an HTTP header to convey the username (hint: you might parse SSL_CLIENT_S_DN_Email)
  • adding credentials (e.g., mailhost, username, password) to a prefs backend so you can use hordeauth

Perhaps, by the time you read this, someone will have written an X509 Auth driver for Horde. A X509 authentication driver is available in Horde_Auth since version 2.0.7 and support for it in the Horde stack is in Horde 5.2.

Web server setup

Most of the work will come in setting up authentication for your web server;

Apache

Apache uses the FakeBasicAuth directive to establish authentication using user certificates, and these instructions assume you are using Apache with mod_ssl support

You setup authentication within either the virtual host or directory directive stanza for your Horde services.

You should read the SSL/TLS Strong Encryption How-To in the Apache man pages for the version of Apache you are using (that link is for version 2.0, though it should be very similar for versions 1.3 and 2.2). This link addresses Client Authentication and Access Control, but you should read the note at the top of the page and take it to heart. The mod_ssl pages on Client Authentication and Access Control are also valuable.


Two possible scenarios for X509 authentication follow:

A fairly strict authentication setup for one or two administrators

<Directory [absolute path to directory for service, in quotes]>
        SSLOptions  +StdEnvVars +ExportCertData +FakeBasicAuth +OptRenegotiate +CompatEnvVars
        SSLVerifyClient   require
        SSLVerifyDepth    5
        SSLRequireSSL
        SSLRequire %{SSL_CLIENT_I_DN_CN} eq "the CN of the Issuer DN of client's certificate in quotes"  
         and %{SSL_CLIENT_S_DN_O} eq "the O of the Subject DN in client's certificate in quotes"  
         and %{SSL_CLIENT_S_DN_CN} in {"the CN of one or more", "comma delimited Subject DNs in quotes"}
</Directory>

An authentication setup for many users with certs from a given CA

<Directory [path to directory where the application lives, in quotes]>
        SSLOptions  +StdEnvVars +ExportCertData +OptRenegotiate +FakeBasicAuth
        SSLVerifyClient   require
        SSLVerifyDepth    5
        SSLRequireSSL 
        SSLRequire %{SSL_CLIENT_I_DN_CN} eq "the CN of Issuer DN of client's certificate in quotes"  
         and %{SSL_CLIENT_S_DN_O} eq "the O of Subject DN in client's certificate in quotes"  
         and %{SSL_CLIENT_S_DN_OU} eq ""the OU of Subject DN in client's certificate in quotes"
</Directory>


Notes

*You will want to read the mod_ssl docs, particularly those for deciphering the certificate-specific environment variables (as in the examples above); you will want to choose the ones relevant to your use.

*You will want to adjust some of the values above (like SSLVerifyDepth) for your own needs. Do NOT just plug in these values.

Lighttpd

Lighttpd, as usual, does not have configuration options as robust as Apache, but the basic setup can still be achieved. Again, You must have SSL properly setup and working.

# These are "normal" SSL directives, not specific to client certs.
ssl.engine                  = "enable"
ssl.pemfile                 = "/opt/local/etc/lighttpd/server.pem"
ssl.ca-file                 = "/opt/local/etc/lighttpd/ca-certs.crt"
server.name                 = "www.example.com"
server.document-root        = "/var/www/html"

# These are for enabling client certs
ssl.verifyclient.activate   = "enable"
ssl.verifyclient.enforce    = "enable"
ssl.verifyclient.exportcert = "enable"
ssl.verifyclient.username   = "SSL_CLIENT_S_DN_UID"
# Make sure you use the appropriate value for **you** for depth.
ssl.verifyclient.depth = 2

Horde configuration

You would configure this driver in the Authentication tab of the Horde application setup page. There are two decisions to make regarding configuration:

  1. What field in the X509 certificate contains the value to be used as the horde login (normally SSL_CLIENT_S_DN_CN)
  2. What to do about passwords for hordeauth in applications like IMP.

The first question is easy. What certificate field contains the username. Normally the default is fine. You should be aware, however of the type of value contained in that field. E.g., if it is a bare username or a full email address. Depending on your server setup, you may need to use a authusername hook to normalize the username (see horde/conf/hooks.php).

The second question takes a bit more effort. If using Horde for email, you will need to provide authentication for each user to the IMAP server. There are ways, of course, to get around this if your system is secured and only Horde/IMP is used to access the IMAP server (you can use a single password for all users, configure the IMAP server to accept any password etc...). More likely you will need to provide some mapping of usernames/passwords. This can all be done in a postauthenticate hook. In it, you can provide any means that makes sense for your server to provide the appropriate credentials. You can even perform extra validation by checking the certificate hash against a stored hash. There is an example provided in the hooks file to get you started. The hooks should return the credentials that horde is to use to authenticate anywhere hordeauth is used.

The X509 driver in Horde also provides the ability to perform custom validation. Any of the fields available in the certificate or any of the SSL environment variables passed by the webserver can be used to perform a final check before authentication is granted. For example, since lighttpd does not provide the same level of enforcement in it's configuration as Apache, you could perform these types of checks here. This is done in the x509_validate hook. See horde/conf/hooks.php for details.