[cvs] [Wiki] created: HordeSSLAuthHowTo

[Wiki Guest]

guest [130.219.235.253]  Wed, 07 Jun 2006 11:59:17 -0700

Created page: http://wiki.horde.org/HordeSSLAuthHowTo

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.  Specifially, 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.  Regardless, you will still want to read about...

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

If you are indeed using Apache as your webserver, you would 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 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.