1 WebAuth release 4.7.0
2 (site-wide web authentication system)
3
4 Originally written by Roland Schemers
5 Currently maintained by Russ Allbery <eagle@eyrie.org>
6
7 Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
8 2012, 2013, 2014 The Board of Trustees of the Leland Stanford Junior
9 University. This software is distributed under a BSD-style license.
10 Please see the section LICENSE below for more information.
11
12BLURB
13
14 WebAuth is a web single sign-on system for authenticating users of web
15 services. It relies on redirects to a central login server on the first
16 attempt to access protected resources and stores credentials so that
17 users can access multiple protected sites without reauthenticating. It
18 supports delegation of specific Kerberos credentials to protected sites
19 and authorization of users based on LDAP directory information.
20
21DESCRIPTION
22
23 WebAuth is a comprehensive system for authenticating web users, built on
24 top of Apache. It relies on a central authentication server with which
25 individual web servers negotiate keys (the WebKDC) and a central login
26 server to which users are redirected at their first attempt to access a
27 protected web site (WebLogin). WebAuth uses AES-encrypted chunks of
28 data, called tokens, that can be sent either in URLs or in cookies.
29 These tokens are used to communicate between the login server and each
30 participating web server. The WebAuth protocol can use whatever initial
31 user authentication mechanism is convenient for the local site to
32 establish the user's identity. Once the user has logged in to the login
33 server, their identity is carried in a cookie set by that login server
34 and they will not again need to enter their password until their
35 credentials expire, even if they visit multiple different protected web
36 sites.
37
38 WebAuth currently relies on either Kerberos or Apache to establish the
39 user's identity, although some features are only available if Kerberos
40 is used. Kerberos is currently the only supported mechanism for WebAuth
41 servers to authenticate to the WebKDC. The protocol is sufficiently
42 general, however, to allow other methods to be added.
43
44 WebAuth supports obtaining of credentials on behalf of the user by
45 trusted application servers, allowing cleaner implementation of
46 portal-style applications.
47
48 WebAuth also provides a second module that can do LDAP directory lookups
49 using Kerberos GSS-API authentication and use the result to authorize
50 web clients by privilege groups or provide directory information to web
51 applications in environment variables. This module implements a subset
52 of the capabilities of more general Apache LDAP modules, but provides
53 those features using a simpler and more easily documented syntax.
54
55 For more information on the Stanford WebAuth project, see:
56
57 <http://webauth.stanford.edu/>
58
59 For release history and user-visible changes, see the file NEWS.
60
61REQUIREMENTS
62
63 WebAuth requires the following additional packages:
64
65 Apache 2 version 2.0.43 or later (2.2 or later recommended)
66 APR and APRUtil libraries (come with Apache)
67 OpenSSL 0.9.7 or later
68 MIT Kerberos 1.2.x or later (1.2.8 or later recommended)
69 -or- Heimdal Kerberos (tested with 0.7 or later)
70 cURL 7.10.2 or later
71
72 LDAP support also requires:
73
74 Cyrus SASL 2.x (tested with 2.1.13 and later)
75 OpenLDAP 2.x (tested with 2.1.17 and later)
76
77 Apache must be built with --enable-ssl and --enable-so. Either Apache
78 2.0 or Apache 2.2 should work, but there have been reports of problems
79 with the Apache 2.0 that comes with Solaris 10 x86, so Apache 2.2 is
80 recommended. WebAuth uses apxs to determine the required build flags
81 for Apache modules. Heimdal 0.6 may work, but has not been well-tested.
82 Heimdal 0.7 and later have been tested more extensively.
83
84 The WebAuth Perl bindings should work with Perl 5.8 and later, but are
85 no longer tested with versions earlier than 5.10.
86
87 For optional support for a user information service, which allows
88 WebAuth to do multifactor authentication, support login history, provide
89 level of assurance information, and other integration into local
90 identity management systems, WebAuth also requires the remctl libraries.
91 These can be obtained from:
92
93 <http://www.eyrie.org/~eagle/software/remctl/>
94
95 For all dependency libraries, be aware that primary testing is done on
96 Debian testing and Debian stable with the versions of the libraries
97 currently available there at the time of the release. Using
98 substantially older libraries, or operating systems other than Linux,
99 may require some portability fixes since those builds are not frequently
100 checked, but such fixes (and bug reports) are definitely welcome.
101
102 For the end user, WebAuth requires that the user's browser be able to
103 handle cookies of moderate length (up to 1KB) and URLs of a similar
104 length. Cookies must be enabled for the systems that use WebAuth
105 authentication. All communication with WebAuth servers is required to
106 be over SSL/TLS to protect the user's credentials. No other special
107 browser capabilities are required.
108
109 WebAuth is written in C and requires a C compiler and a standard make
110 program to build. It does not (at least intentionally) use any special
111 make features. WebAuth also requires Perl 5.8 or later and a variety of
112 additional Perl modules for the WebLogin server. Perl is not required
113 for the basic WebAuth module.
114
115 WebAuth is primarily tested with GCC on Linux (glibc 2.3 and later).
116 Earlier releases have been lightly tested on Solaris, Mac OS X, and AIX
117 4.3. Other UNIX and UNIX-like platforms that support Apache should also
118 work, but have not been tested. Some amount of porting may be required.
119 WebAuth does use libtool to try to build shared libraries portably.
120 Windows is not supported.
121
122 WebLogin additionally requires the following Perl modules. All of these
123 are available from CPAN:
124
125 CGI::Application
126 CGI::Application::Plugin::AutoRunmode
127 CGI::Application::Plugin::Forward
128 CGI::Application::Plugin::Redirect
129 CGI::Application::Plugin::TT
130 IO::Socket::SSL
131 libwww (LWP)
132 Template (Template Toolkit)
133 URI
134 XML::Parser
135
136 Perl 5.10 or later is recommended. If you are using an older version of
137 Perl, you will additionally need the following modules to build
138 WebLogin, but not to run it:
139
140 ExtUtils::CBuilder
141 Module::Build
142
143 Some mechanism for running FastCGI scripts under Apache, such as
144 mod_fcgi or mod_fastcgi, is also recommended to improve performance of
145 the WebLogin interface, but this is not required.
146
147 To support replay detection and rate limiting in WebLogin, the following
148 modules are also required:
149
150 Cache::Memcached
151 Digest::SHA (part of Perl itself since 5.9.3)
152
153 The optional WebLogin support for warning users of expired passwords
154 also requires the Perl modules:
155
156 Date::Parse (TimeDate)
157 Net::Remctl
158 Time::Duration
159
160 The test suite requires and Test::More (part of Perl since 5.6.2).
161 Either Perl 5.14 or the JSON::PP Perl module is required. It also makes
162 use of additional Perl modules for some tests. These tests will be
163 skipped automatically if the modules aren't available. To run the full
164 set of default tests, you will need the Perl modules:
165
166 Test::MinimumVersion
167 Test::Pod
168
169 and their dependencies as well as all of the prerequisites listed above.
170 These modules are all available from CPAN.
171
172 Bootstrapping from a Git checkout, or making changes to some of the
173 generated files, will require the following additional packages:
174
175 Autoconf 2.64 or later
176 Automake 1.11 or later
177 Perl 5.10 or later
178 xml2rfc
179
180 To enable tests that don't detect functionality problems but are used to
181 sanity-check the release, set the environment variable RELEASE_TESTING
182 to a true value. To enable tests that may be sensitive to the local
183 environment or that produce a lot of false positives without uncovering
184 many problems, set the environment variable AUTHOR_TESTING to a true
185 value. For these tests, the additional Perl modules:
186
187 Test::Perl::Critic
188 Test::Spelling
189 Test::Strict
190
191 and their dependencies as well as a spell-checking program (several are
192 supported by Test::Spelling) are required. These modules are all
193 available from CPAN.
194
195SUPPORT
196
197 New WebAuth releases are announced via the low-volume webauth-announce
198 mailing list. To subscribe or see the list archives, go to:
199
200 https://mailman.stanford.edu/mailman/listinfo/webauth-announce
201
202 There is also a separate mailing list for general discussion and
203 requests for help, which is also read by members of the WebAuth project
204 team. To subscribe or see the list archives, go to:
205
206 https://mailman.stanford.edu/mailman/listinfo/webauth-info
207
208 Stanford users may instead read and post to the newsgroup
209 su.computers.webauth, which is bidirectionally gatewayed to
210 webauth-info. The newsgroup additionally gets all messages to
211 webauth-announce as well.
212
213 For Stanford affiliates, the WebAuth modules are a supported product
214 of the ITS Infrastructure Delivery Group. You can report problems or
215 request help with WebAuth by submitting a HelpSU ticket at:
216
217 <https://remedyweb.stanford.edu/helpsu/helpsu>
218
219 Please note that we do not support Apache, and we cannot help you set up
220 a web server. We can help you configure WebAuth and may provide a
221 prebuilt Apache server for your platform for convenience, but general
222 web server problems unrelated to WebAuth are outside the scope of what
223 we can help with.
224
225 For non-Stanford users, please instead subscribe to webauth-info and ask
226 your question there. We cannot provide any formal support for
227 non-Stanford users, nor do we make any promises or committments related
228 to this software. Please feel free to use it on an as-is basis, and
229 please do feel free to send us any patches or improvements that you wish
230 to contribute and we will evaluate them for future releases. However,
231 please be aware that our primary focus is supporting the needs of
232 Stanford University and work on features not used by Stanford is mostly
233 done on a volunteer basis.
234
235SOURCE REPOSITORY
236
237 WebAuth is maintained using Git. You can access the current source by
238 cloning the repository at:
239
240 git://git.eyrie.org/kerberos/webauth.git
241
242 or view the repository via the web at:
243
244 http://git.eyrie.org/?p=kerberos/webauth.git
245
246 When contributing modifications, patches (possibly generated by
247 git-format-patch) are preferred to Git pull requests.
248
249CREDITS
250
251 The WebAuth v3 protocol and core implementation was written by Roland
252 Schemers, based on design documents by the entire Stanford WebAuth team
253 (with considerable work by Tim Torgenrud and Booker Bense) and based in
254 part on the functionality of WebAuth v2.5, written and maintained by a
255 cast of dozens over the years but most notably Jeff Lewis, Anton
256 Ushakov, and Jeanmarie Lucker.
257
258 The mod_webauthldap module was written by Anton Ushakov.
259
260 The configuration and build system and WebAuth packaging was put
261 together by Russ Allbery. Huaqing Zheng provided builds of supporting
262 packages and Jonathan Pilat helped greatly with testing. Xueshan Feng
263 oversaw the project.
264
265 The WebAuth package is currently maintained by Russ Allbery. Jon
266 Robertson does much of the maintenance work on the WebLogin code and
267 implemented password change and multifactor support.
268
269 RPMs are built by Darren Patterson based on earlier work by Joe Little.
270 Many of the Solaris packages were built by Quanah Gibson-Mount.
271
272 Thanks to pod for improvements, particularly to the WebKDC, to make it
273 easier to package for a Linux distribution, for the initial Debian
274 package build rules, and for generic WebKDC templates suitable for a new
275 installation and for use as examples.
276
277 Thanks to Dmitri Priimak for work on cross-realm support, WebLogin
278 improvements, and testing of unusual Kerberos realms and principal
279 names.
280
281LICENSE
282
283 The WebAuth package as a whole covered by the following copyright
284 statement and license:
285
286 Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
287 2012, 2013, 2014
288 The Board of Trustees of the Leland Stanford Junior University
289
290 Permission is hereby granted, free of charge, to any person obtaining
291 a copy of this software and associated documentation files (the
292 "Software"), to deal in the Software without restriction, including
293 without limitation the rights to use, copy, modify, merge, publish,
294 distribute, sublicense, and/or sell copies of the Software, and to
295 permit persons to whom the Software is furnished to do so, subject to
296 the following conditions:
297
298 The above copyright notice and this permission notice shall be
299 included in all copies or substantial portions of the Software.
300
301 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
302 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
303 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
304 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
305 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
306 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
307 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
308
309 All individual files without an explicit exception below are released
310 under this license. Some files may have additional copyright holders as
311 noted in those files. There is detailed information about the licensing
312 of each file in the LICENSE file in this distribution.
313
314 Some files in this distribution are individually released under
315 different licenses, all of which are compatible with the above general
316 package license but which may require preservation of additional
317 notices. All required notices are preserved in the LICENSE file.
318