Lets say you are in a domain, and you wish to access several different web services. How often do you find you have to enter the same username and password over and over again to get to each website? Wouldn’t it be nice if you could just enter it once and automagically have access to all the web services you need? Well guess what? You can!
It all works off of MIT Kerberos. Kerberos is a mechanism that centralizes your authentication to one service and allows for Single Sign-On. The concept of SSO is fairly simple: Enter your credentials once and that’s it. It save you from typing them over and over again and protects against certain attacks.
WebAuth was developed at Stanford University and brings “kerberization” to web services. All you need is some modules, a KDC, and a webserver.
In this guide, we will be utilizing the Kerberos realm/domain name of EXAMPLE.COM. We will also be using two servers:
- gmcsrvx2.example.com: The Webauth WebKDC
- gmcsrvx3.example.com: A secondary web server
- webauth.example.com: A DNS CNAME to gmcsrvx2.example.com
Note that you will need a pre-existing Kerberos KDC in your network.
There are three components of the WebAuth system. WebAuth typically refers to the component that provides authorized access to certain content. The WebKDC is the process that handles communication with the Kerberos KDC and distributes tickets out to the client machines. The WebLogin pages are the login/logoff/password change pages that are presented to the user to enter their credentials. Certain binary packages provided by Stanford do not contain components of the WebAuth system. This is why we are going to build it from source.
Each machine you plan to install WebAuth on needs the following packages:
Enterprise Linux does not include several required Perl modules for this to work. You are going to need to install them via CPAN. If you have never run CPAN before, do it once just to get the preliminary setup working.
You also need Remctl, an interface to Kerberos. For EL6 we are using remctl 2.11 available from the Fedora 15 repositories.
1 2 3
Open up ports 80 (HTTP) and 443 (HTTPS) since we will be doing web stuff.
Since you will be doing Kerberos stuff, you need a synchronized clock. If you do not know how to do this, see my guide on Setting up NTP.
Your machine needs to be a Kerberos client (meaning valid DNS, krb5.conf, and host prinicpal in its /etc/krb5.keytab). We will be using three keytabs for this application:
- service/webkdc@EXAMPLE.COM NOTE: If you wrote these in your home directory and cp’d them into their respective paths, check your SELinux contexts.
You need an SSL certificate matching the hostname of each server (gmcsrvx2.example.com, gmcsrvx3.example.com, webauth.example.com) avaiable for your Apache configuration.
IMPORTANT:You also need to ensure that your CA is trusted by Curl (the system). If in doubt, cat your CA cert into
/etc/pki/tls/certs/ca-bundle.crt. You will get really odd errors if you do not do this.
We will be installing WebAuth into
/usr/local and this need its libraries to be linked in the system.
We will need to run
ldconfig to load in the WebAuth libraries later on.
Compile and Install WebAuth
The latest version at the time of this writing is webauth-4.1.1 and is avaiable from Stanford University. Grab the source tarball since the packages do not include features that you will need in a brand new installation.
1 2 3 4 5 6 7 8 9 10 11 12
Assuming everything is all good, go ahead and build it.
1 2 3 4 5 6 7 8 9
And assuming everything is happy, make install:
1 2 3 4 5 6 7 8 9
Now ensure that the new libraries get loaded by running
ldconfig. This looks at the files in that ld.so.conf.d directory and adds them to the library path. MAKE SURE YOU DO THIS!!!
The Apache modules for WebAuth have been compiled into
Make sure you have the proper keytab set up at
/etc/webauth/webauth.keytab. This file can technically be located anywhere as long as you configure the module accordingly.
Next you need to create a local state directory for WebAuth. Usually this is
/var/lib/webauth. The path can be changed as long as you set it in the following configuration file.
The Apache module needs a configuration file to be included in the Apache server configuration. On Enterprise Linux, this can be located in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
Again, adjust paths to suit your tastes. The
WebAuthWebKdcSSLCertFile should be your public CA certificate that you probably cat’d earlier.
Make sure you have the proper keytab set up at
/etc/webkdc/webkdc.keytab. This file can technically be located anywhere as long as you configure the module accordingly.
Next you need to create a local state directory for the WebKDC. Usually this is
/var/lib/webkdc. The path can be changed as long as you set it in the configuration files.
The WebKDC utilizes an ACL to allow only certain hosts to get tickets. This goes in
1 2 3
For the WebLogin pages, another configuration file is used to specify the information for it (in
/etc/webkdc/webkdc.conf). This is seperate from the Apache module configuration loaded by the webserver.
1 2 3 4 5
NOTE: You CANNOT change the location of this file or the WebKDC module will freak out.
Note that certain directives must match the Apache configuration. We will make that now in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Ensure that your paths match what you set up earlier.
This step should only be done if you have an LDAP server operating in your network and can accept SASL binds. You can make certain LDAP attributes available in the web environment as server variables for your web applications. This is configured in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
Most of the files that you created do not have the appropriate permissions to be read/written by the webserver. Lets fix that.
1 2 3 4 5 6 7 8 9 10 11
I created a VHost for both “webauth.example.com” and “gmcsrvx2.example.com”, with the latter requiring user authentication to view. I name these after the hostname they are serving in
/etc/httpd/conf.d/webauth.conf, Just throw a simple Hello World into the DocumentRoot that you configure for your testing host. Note that you must have NameVirtualHost-ing setup for both ports 80 and 443.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
And the host file at
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
Once you are all set, start Apache. Then navigate your web browser to the host (http://gmcsrvx2.example.com). This should first redirect you to HTTPS, then bounce you to the WebLogin pages. After authenticating, you should be able to access the server.
This is by no means a simple thing to get set up. An intimate knowlege how how Kerberos, Apache, and LDAP work is crucial to debugging issues relating to WebAuth. All of my sample configuration files can be found in the Archive.