Obtaining and Installing WebAuth
Before starting to install WebAuth, take a moment to consider what your goals are. WebAuth is an add-on module for the Apache web server, a fairly large and complex piece of software. It requires a Unix server, and will require time, study, and care to install and maintain properly. As with any network-accessible server, you won't be done when you manage to get it all installed and working. You will also need to watch for security advisories and patches and upgrade the server when necessary.
Many Stanford content providers do not need to run their own web server and can simply use the central web hosting resources already available. Stanford users can host their pages on www.stanford.edu and use many WebAuth features for their pages without having to run their own servers. Stanford also provides a proxy server that can authenticate users with WebAuth and provide that information in the HTTP header to other servers.
Make sure that you really want to and need to put the work into installing and maintaining your own Apache and WebAuth server before you start working on it.
WebAuth is available as source, Debian packages, and Red Hat patches. Users on other platforms will need compile it themselves. Contributed but unsupported Windows and Java ports are also available.
In order to install WebAuth via any method other than Debian or Red Hat packages, you will first need to download and install several pre-requisite packages:
and for LDAP support (with GSS-API binds):
Debian and Red Hat package installations will install the prerequisites automatically.
For other Linux users, OpenSSL, cURL, Kerberos, Cyrus SASL, and OpenLDAP should all be available from your distribution. Note that in order to build WebAuth, you will need to install the -dev or -devel versions of the packages as well as the basic packages (that includes Apache).
Compiling and Installing
If you are installing WebAuth at Stanford, please read the Stanford-specific instructions.
If you are compiling WebAuth yourself, the first step is to make sure that you have a compiler installed. Linux users will be able to install gcc and other development tools from their Linux distribution. Solaris users will to either install gcc or obtain the Solaris commercial compiler.
WebAuth has primarily been tested with gcc. It should build with any reasonable C compiler, but building with various commercial compilers is not regularly tested.
Once you have compiled WebAuth, follow the installation instructions. If you are familiar with WebAuth v2, the previous Stanford web authentication system, you may want to read the notes on upgrading from WebAuth v2.
The above installation instructions include basic configuration instructions, and here is an annotated version. For more details and reference information for all of the possible WebAuth module directives, see the mod_webauth reference manual.
If you are installing WebAuth at Stanford, see the Stanford-specific installation instructions.
See user authentication and authorization with WebAuth for information about how to protect all or portions of your web site with WebAuth.
If you also need LDAP information, see the mod_webauthldap reference manual for information on how to configure the LDAP module.
WebAuth with the LDAP module allows you to restrict access by membership in a privilege group maintained in the directory servers. Stanford users should go to workgroup.stanford.edu to create and manage these privilege groups.
Other Supporting Software
The following additional software packages also work with WebAuth and may be of use to you. One of them is also supported by the WebAuth development team:
The WebAuth web authentication system defines a user information service protocol that's used to determine what factors a given user has access to and to validate OTP codes used for authentication to the central WebLogin server. This PAM module uses the same protocol to talk to the same WebAuth user information service when validating OTP codes for interactive PAM-based logins. Currently, SMS is not supported, only OTP methods that don't require a multi-step user interaction.
The remaining additional software was written by third parties. Please note that the WebAuth team does not support any of this software, only provides links for the convenience of WebAuth users. However, announcement and discussion of this software is welcome on the WebAuth mailing lists.
Rack middleware to acquire authentication information from a Stanford WebAuth system, useful for Ruby web application developers. It allows easy access to information placed into the environment by WebAuth, including attributes from mod_webauthldap. It is available as Ruby source and as a Ruby gem under the terms of the GNU Lesser General Public License (LGPL) v3.
- Shibboleth IdP WebLogin Handler
An enhanced Shibboleth IdP authentication handler that integrates with WebAuth. One can use the standard RemoteUser authentication handler, but it cannot support forced authentication. This page and the included software explains how to support forced authentication in Shibboleth with WebAuth.
If you are installing WebAuth from the ground up at a new site, you have to also install a new WebKDC and associated Weblogin server. This is not necessary if WebAuth is already running at your site (such as at Stanford); it's only necessary when doing the initial WebAuth installation at your site.
If you are bringing up a new WebKDC, read the WebKDC installation instructions and the Weblogin configuration and customization instructions.
After you have the WebKDC up and running, you may want to also enable SPNEGO authentication support in the Weblogin server. If many of your clients have Kerberos installed on their desktops and use browsers capable of doing SPNEGO authentication (current Firefox, Safari, IE), this allows them to authenticate to WebAuth without entering their username and password on the Weblogin page. For details, see the SPNEGO installation instructions.
For information on how to enable multifactor authentication, see the multifactor installation instructions.
If you use SPNEGO or any other Apache authentication mechanism, the page flow for the Weblogin server becomes somewhat more complicated. You may want to read through the Weblogin page flow documentation to understand it.
You may also want to review the documentation for cookies used by the WebLogin server.