Fix URL to HelpSU

[kerberos/webauth.git] / README

                          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://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.  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.