WebAuth release 4.7.0

(site-wide web authentication system)

Originally written by Roland Schemers
Currently maintained by Russ Allbery <eagle@eyrie.org>

Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 The Board of Trustees of the Leland Stanford Junior University. This software is distributed under a BSD-style license. Please see the section LICENSE below for more information.

BLURB

WebAuth is a web single sign-on system for authenticating users of web services. It relies on redirects to a central login server on the first attempt to access protected resources and stores credentials so that users can access multiple protected sites without reauthenticating. It supports delegation of specific Kerberos credentials to protected sites and authorization of users based on LDAP directory information.

DESCRIPTION

WebAuth is a comprehensive system for authenticating web users, built on top of Apache. It relies on a central authentication server with which individual web servers negotiate keys (the WebKDC) and a central login server to which users are redirected at their first attempt to access a protected web site (WebLogin). WebAuth uses AES-encrypted chunks of data, called tokens, that can be sent either in URLs or in cookies. These tokens are used to communicate between the login server and each participating web server. The WebAuth protocol can use whatever initial user authentication mechanism is convenient for the local site to establish the user's identity. Once the user has logged in to the login server, their identity is carried in a cookie set by that login server and they will not again need to enter their password until their credentials expire, even if they visit multiple different protected web sites.

WebAuth currently relies on either Kerberos or Apache to establish the user's identity, although some features are only available if Kerberos is used. Kerberos is currently the only supported mechanism for WebAuth servers to authenticate to the WebKDC. The protocol is sufficiently general, however, to allow other methods to be added.

WebAuth supports obtaining of credentials on behalf of the user by trusted application servers, allowing cleaner implementation of portal-style applications.

WebAuth also provides a second module that can do LDAP directory lookups using Kerberos GSS-API authentication and use the result to authorize web clients by privilege groups or provide directory information to web applications in environment variables. This module implements a subset of the capabilities of more general Apache LDAP modules, but provides those features using a simpler and more easily documented syntax.

For more information on the Stanford WebAuth project, see:

<http://webauth.stanford.edu/>

For release history and user-visible changes, see the file NEWS.

REQUIREMENTS

WebAuth requires the following additional packages:

    Apache 2 version 2.0.43 or later (2.2 or later recommended)
    APR and APRUtil libraries (come with Apache)
    OpenSSL 0.9.7 or later
    MIT Kerberos 1.2.x or later (1.2.8 or later recommended)
      -or- Heimdal Kerberos (tested with 0.7 or later)
    cURL 7.10.2 or later

LDAP support also requires:

    Cyrus SASL 2.x (tested with 2.1.13 and later)
    OpenLDAP 2.x (tested with 2.1.17 and later)

Apache must be built with --enable-ssl and --enable-so. Either Apache 2.0 or Apache 2.2 should work, but there have been reports of problems with the Apache 2.0 that comes with Solaris 10 x86, so Apache 2.2 is recommended. WebAuth uses apxs to determine the required build flags for Apache modules. Heimdal 0.6 may work, but has not been well-tested. Heimdal 0.7 and later have been tested more extensively.

The WebAuth Perl bindings should work with Perl 5.8 and later, but are no longer tested with versions earlier than 5.10.

For optional support for a user information service, which allows WebAuth to do multifactor authentication, support login history, provide level of assurance information, and other integration into local identity management systems, WebAuth also requires the remctl libraries. These can be obtained from:

<http://www.eyrie.org/~eagle/software/remctl/>

For all dependency libraries, be aware that primary testing is done on Debian testing and Debian stable with the versions of the libraries currently available there at the time of the release. Using substantially older libraries, or operating systems other than Linux, may require some portability fixes since those builds are not frequently checked, but such fixes (and bug reports) are definitely welcome.

For the end user, WebAuth requires that the user's browser be able to handle cookies of moderate length (up to 1KB) and URLs of a similar length. Cookies must be enabled for the systems that use WebAuth authentication. All communication with WebAuth servers is required to be over SSL/TLS to protect the user's credentials. No other special browser capabilities are required.

WebAuth is written in C and requires a C compiler and a standard make program to build. It does not (at least intentionally) use any special make features. WebAuth also requires Perl 5.8 or later and a variety of additional Perl modules for the WebLogin server. Perl is not required for the basic WebAuth module.

WebAuth is primarily tested with GCC on Linux (glibc 2.3 and later). Earlier releases have been lightly tested on Solaris, Mac OS X, and AIX 4.3. Other UNIX and UNIX-like platforms that support Apache should also work, but have not been tested. Some amount of porting may be required. WebAuth does use libtool to try to build shared libraries portably. Windows is not supported.

WebLogin additionally requires the following Perl modules. All of these are available from CPAN:

    CGI::Application
    CGI::Application::Plugin::AutoRunmode
    CGI::Application::Plugin::Forward
    CGI::Application::Plugin::Redirect
    CGI::Application::Plugin::TT
    IO::Socket::SSL
    libwww (LWP)
    Template (Template Toolkit)
    URI
    XML::Parser

Perl 5.10 or later is recommended. If you are using an older version of Perl, you will additionally need the following modules to build WebLogin, but not to run it:

    ExtUtils::CBuilder
    Module::Build

Some mechanism for running FastCGI scripts under Apache, such as mod_fcgi or mod_fastcgi, is also recommended to improve performance of the WebLogin interface, but this is not required.

To support replay detection and rate limiting in WebLogin, the following modules are also required:

    Cache::Memcached
    Digest::SHA (part of Perl itself since 5.9.3)

The optional WebLogin support for warning users of expired passwords also requires the Perl modules:

    Date::Parse (TimeDate)
    Net::Remctl
    Time::Duration

The test suite requires and Test::More (part of Perl since 5.6.2). Either Perl 5.14 or the JSON::PP Perl module is required. It also makes use of additional Perl modules for some tests. These tests will be skipped automatically if the modules aren't available. To run the full set of default tests, you will need the Perl modules:

    Test::MinimumVersion
    Test::Pod

and their dependencies as well as all of the prerequisites listed above. These modules are all available from CPAN.

Bootstrapping from a Git checkout, or making changes to some of the generated files, will require the following additional packages:

    Autoconf 2.64 or later
    Automake 1.11 or later
    Perl 5.10 or later
    xml2rfc

To enable tests that don't detect functionality problems but are used to sanity-check the release, set the environment variable RELEASE_TESTING to a true value. To enable tests that may be sensitive to the local environment or that produce a lot of false positives without uncovering many problems, set the environment variable AUTHOR_TESTING to a true value. For these tests, the additional Perl modules:

    Test::Perl::Critic
    Test::Spelling
    Test::Strict

and their dependencies as well as a spell-checking program (several are supported by Test::Spelling) are required. These modules are all available from CPAN.

SUPPORT

New WebAuth releases are announced via the low-volume webauth-announce mailing list. To subscribe or see the list archives, go to:

    https://mailman.stanford.edu/mailman/listinfo/webauth-announce

There is also a separate mailing list for general discussion and requests for help, which is also read by members of the WebAuth project team. To subscribe or see the list archives, go to:

    https://mailman.stanford.edu/mailman/listinfo/webauth-info

Stanford users may instead read and post to the newsgroup su.computers.webauth, which is bidirectionally gatewayed to webauth-info. The newsgroup additionally gets all messages to webauth-announce as well.

For Stanford affiliates, the WebAuth modules are a supported product of the ITS Infrastructure Delivery Group. You can report problems or request help with WebAuth by submitting a HelpSU ticket at:

<https://remedyweb.stanford.edu/helpsu/helpsu>

Please note that we do not support Apache, and we cannot help you set up a web server. We can help you configure WebAuth and may provide a prebuilt Apache server for your platform for convenience, but general web server problems unrelated to WebAuth are outside the scope of what we can help with.

For non-Stanford users, please instead subscribe to webauth-info and ask your question there. We cannot provide any formal support for non-Stanford users, nor do we make any promises or committments related to this software. Please feel free to use it on an as-is basis, and please do feel free to send us any patches or improvements that you wish to contribute and we will evaluate them for future releases. However, please be aware that our primary focus is supporting the needs of Stanford University and work on features not used by Stanford is mostly done on a volunteer basis.

SOURCE REPOSITORY

WebAuth is maintained using Git. You can access the current source by cloning the repository at:

    git://git.eyrie.org/kerberos/webauth.git

or view the repository via the web at:

    http://git.eyrie.org/?p=kerberos/webauth.git

When contributing modifications, patches (possibly generated by git-format-patch) are preferred to Git pull requests.

CREDITS

The WebAuth v3 protocol and core implementation was written by Roland Schemers, based on design documents by the entire Stanford WebAuth team (with considerable work by Tim Torgenrud and Booker Bense) and based in part on the functionality of WebAuth v2.5, written and maintained by a cast of dozens over the years but most notably Jeff Lewis, Anton Ushakov, and Jeanmarie Lucker.

The mod_webauthldap module was written by Anton Ushakov.

The configuration and build system and WebAuth packaging was put together by Russ Allbery. Huaqing Zheng provided builds of supporting packages and Jonathan Pilat helped greatly with testing. Xueshan Feng oversaw the project.

The WebAuth package is currently maintained by Russ Allbery. Jon Robertson does much of the maintenance work on the WebLogin code and implemented password change and multifactor support.

RPMs are built by Darren Patterson based on earlier work by Joe Little. Many of the Solaris packages were built by Quanah Gibson-Mount.

Thanks to pod for improvements, particularly to the WebKDC, to make it easier to package for a Linux distribution, for the initial Debian package build rules, and for generic WebKDC templates suitable for a new installation and for use as examples.

Thanks to Dmitri Priimak for work on cross-realm support, WebLogin improvements, and testing of unusual Kerberos realms and principal names.

LICENSE

The WebAuth package as a whole covered by the following copyright statement and license:

  Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
    2012, 2013, 2014
    The Board of Trustees of the Leland Stanford Junior University
  Permission is hereby granted, free of charge, to any person obtaining
  a copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:
  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

All individual files without an explicit exception below are released under this license. Some files may have additional copyright holders as noted in those files. There is detailed information about the licensing of each file in the LICENSE file in this distribution.

Some files in this distribution are individually released under different licenses, all of which are compatible with the above general package license but which may require preservation of additional notices. All required notices are preserved in the LICENSE file.

Converted to XHTML by faq2html version 1.33