                          WebAuth release 3.7.1
                  (site-wide web authentication system)

  Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Board of
  Trustees, Leland Stanford Jr.  University.  This software is distributed
  under an MIT-style license.  Please see the file LICENSE in the
  distribution for terms of use and redistribution.

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

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 2.0.  It relies on a login server (the WebKDC) to which
  users are redirected at their first attempt to access a protected web
  site, uses AES-encrypted chunks of data called tokens which can be sent
  either in URLs or in cookies and are used to communicate between the
  login server and each participating web server, and implements a
  protocol able to use whichever initial user authentication mechanism is
  convenient 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 relies on either Kerberos v5 or Apache to establish the user's
  identity, although some features are only available if Kerberos v5 is
  used.  Kerberos v5 is 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 v5 GSS-API authentication and use the result to authorize
  web clients by privilege groups or provide directory information to web
  applications in environment variables.

  For more information on the Stanford WebAuth project, see:

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

  This is a substantial reworking of the previous Stanford WebAuth system,
  which was based primarily around the S/Ident protocol for user
  authentication but supported a fallback to a web login server and used
  domain-wide cookies to pass that authentication information to
  individual web servers.  This implementation was heavily inspired by
  that previous work but shares no common code, only uses cookies scoped
  to individual systems, and is now built primarily around the login
  server model with "web single sign-on" (single sign-on that works for
  all authenticated web sites within an authentication realm, but which
  does not necessarily tie into desktop single sign-on systems).

REQUIREMENTS

  WebAuth requires the following additional packages:

      Apache 2 version 2.0.43 or later (2.0.46 or later recommended)
      OpenSSL 0.9.7 or later
      MIT Kerberos v5 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 without difficulty.  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 have been tested with Perl 5.6.1 and later,
  but are no longer tested with versions earlier than 5.10.

  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 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.6.1 or later 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).  It
  has been lightly tested on Solaris and Mac OS X, and earlier releases
  were tested on AIX 4.3.  Other Unix platforms that support Apache 2.0 or
  2.2 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.

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

      HTML::Template
      libwww (LWP)
      IO::Socket::SSL -or- Crypt::SSLeay (for LWP https support)
      URI
      XML::Parser

  The Apache mod_fastcgi module is also recommended to speed up the
  WebLogin interface, but is not required.

  For optional WebLogin support for warning users of expired passwords,
  the Net::Remctl Perl module is required and the local Kerberos realm
  must provide the remctl interface from the kadmin-remctl package for the
  WebLogin script to query.  You can obtain Net::Remctl and kadmin-remctl
  from:

      http://www.eyrie.org/~eagle/software/remctl/
      http://www.eyrie.org/~eagle/software/kadmin-remctl/

  respectively.

  To bootstrap from a Git checkout, or if you change the Automake files
  and need to regenerate Makefile.in, you will need Automake 1.11 or
  later.  For bootstrap or if you change configure.ac or any of the m4
  files it includes and need to regenerate configure or config.h.in, you
  will need Autoconf 2.64 or later.  Perl and xml2rfc are also required to
  generate the manual pages and protocol documentation from a fresh Git
  checkout.

SUPPORT

  New WebAuth releases are announced via the low-volume webauth-announce
  mailing list.  To subscribe, send mail to majordomo@lists.stanford.edu
  with:

      subscribe webauth-announce

  in the body of the message.

  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, send mail to majordomo@lists.stanford.edu with:

      subscribe webauth-info

  in the body of the message.  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 ITSS Infrastructure Services team.  You can report problems or
  request help with WebAuth by submitting a HelpSU ticket at:

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

  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.  Our
  primary focus is supporting the needs of Stanford University, however,
  and problems that don't affect Stanford's use of WebAuth will generally
  not be prioritized.

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.

  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.

  Thanks to Jon Robertson for implementing password change support for
  WebLogin.
