6.0.0-git
2019-11-19

Diff for HordeSSLAuthHowTo between 4 and 5

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

[[toc]]

+++ 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 [http://en.wikipedia.org/wiki/Public_key_infrastructure 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.

**##red|//But Wait!//##**

Authenticating using X509 user certificates has more in common with using the [http://wiki.horde.org/ShibbolethAuthHowTo 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,@@--- Perhaps, by the time you read this, someone will have written an X509 Auth driver for Horde.  Regardless, you will still want to read about...+++ 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;  these instructions are for **Apache** - hopefully, someone will add similar instructions for other web servers.

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

IfApache uses the !FakeBasicAuth directive to establish authentication using user certificates, and **these instructions assume you are indeed using Apache as your webserver, you wouldwith mod_ssl support** 

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

You should read the [http://httpd.apache.org/docs/2.0/ssl/ssl_howto.html 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//).  [http://httpd.apache.org/docs/2.0/ssl/ssl_howto.html#accesscontrol 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 [http://www.modssl.org/docs/2.8/ssl_howto.html#ToC6 Client Authentication and Access Control] are also valuable.

----

+++ Two

Two possible scenarios for X509 authentication follow:

++++

+++++ A fairly strict authentication setup for one or two administrators
<code>
<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>
</code>
++++
+++++ An authentication setup for many users with certs from a given CA
<code>
<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>
</code>
----
++++++++ Notes
*You **will** want to read the mod_ssl docs, particularly those for deciphering the certificate-specific [http://www.modssl.org/docs/2.8/ssl_compat.html#ToC2 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.

++ Link++++ 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**.

<code>
# 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
</code>


+++ 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:

# What field in the X509 certificate contains the value to be used as the horde login (normally SSL_CLIENT_S_DN_CN)
# 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.