[commits] [Wiki] changed: HordeSSLAuthHowTo
Michael Rubinsky
mrubinsk at horde.org
Wed Aug 28 04:27:15 UTC 2013
mrubinsk Wed, 28 Aug 2013 04:27:15 +0000
Modified page: http://wiki.horde.org/HordeSSLAuthHowTo
New Revision: 5
Change log: Add info about the X509 auth driver.
@@ -13,24 +13,26 @@
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, by the time you read this, someone will have written an X509
Auth driver for Horde. Regardless, you will still want to read about...
+@@--- 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; these instructions are for **Apache** - hopefully, someone
will add similar instructions for other web servers.
+Most of the work will come in setting up authentication for your web server;
-Apache uses the !FakeBasicAuth directive to establish authentication
using user certificates, and **these instructions assume you are using
Apache with mod_ssl support**
+++++ Apache
-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.
+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
[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:
+Two possible scenarios for X509 authentication follow:
-++++ A fairly strict authentication setup for one or two administrators
++++++ 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
@@ -40,9 +42,9 @@
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
++++++ 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
@@ -53,11 +55,43 @@
and %{SSL_CLIENT_S_DN_OU} eq ""the OU of Subject DN in
client's certificate in quotes"
</Directory>
</code>
----
-+++ Notes
++++++ 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.
More information about the commits
mailing list