1 WebAuth Installation Instructions
5 These installation instructions are for the typical WebAuth user who
6 wants to set up a web server with content protected by WebAuth and
7 take advantage of an existing site WebAuth infrastructure (including a
8 login server and WebKDC). For details on how to install the site
9 infrastructure, which is more complex and only has to be done once at
10 each site, see doc/install-webkdc.
12 If you have installed the Debian or Ubuntu packages, please see
13 /usr/share/doc/libapache2-webauth/README.Debian.gz, which is more
14 complete and specific for using those packages than these
19 Make sure that you have all of the required packages installed.
20 WebAuth is implemented as Apache 2.x modules, and therefore requires
21 an installation of Apache 2.0.43 or later built with SSL and dynamic
22 modules. There are reports of problems with Apache 2.0.x as shipped
23 with Solaris 10 x86, so Apache 2.2 or later is recommended. It also
24 requires Kerberos, cURL, and OpenSSL 0.9.7 or later (for AES support).
25 See README for more version dependencies.
27 In order to build the LDAP module, Cyrus SASL 2.x and OpenLDAP are
30 Note that all of these packages should be installed on local disk. We
31 do not recommend using libraries installed on shared file systems such
32 as AFS, since the reliability of your web server will then be tied to
33 the availability of that remote file system. The required libraries
34 aren't large, particularly given the average size of modern disks.
36 If you build your own Apache 2.x server, you'll want to use a
37 configure invocation like:
39 ./configure --enable-so --enable-ssl --with-ssl=/usr/local
41 (changing the last if your OpenSSL is installed somewhere else). Any
42 pre-packaged Apache server should be built this way.
44 If you are building a Git clone of the WebAuth distribution (as
45 opposed to a packaged release, which already includes the generated
46 configure script), cd to the top of the source tree and run:
50 to generate the configure script. Autoconf 2.64 and Automake 1.11 or
51 later are required, Perl is required to generate the man pages, and
52 xml2rfc is required to build the protocol documentation.
56 Run configure. The command will look something like:
58 ./configure --with-apxs=/usr/local/apache2/bin/apxs \
59 --with-openssl=/usr/local --with-ldap=/usr/local
61 configure will detect various things about your system and will
62 generate the makefiles and include files required to build WebAuth.
64 Adjust the paths to match where you have installed those packages.
65 You can omit --with-openssl and --with-ldap if the packages are
66 installed in locations automatically searched by your compiler and
67 linker (which will be the case if you're using Linux and the packages
68 that come with your Linux distribution).
70 You can omit --with-apxs if the right version of apxs is in your path.
72 Normally, configure will use krb5-config to determine the flags to use
73 to compile with your Kerberos GSS-API libraries. If krb5-config isn't
74 found, it will look for the standard Kerberos libraries in locations
75 already searched by your compiler. If the krb5-config script first in
76 your path is not the one corresponding to the Kerberos libraries you
77 want to use or if your Kerberos libraries and includes aren't in a
78 location searched by default by your compiler, you need to specify
81 ./configure --with-krb5=/usr/local
83 You can also individually set the paths to the include directory and
84 the library directory with --with-krb5-include and --with-krb5-lib.
85 You may need to do this if Autoconf can't figure out whether to use
86 lib, lib32, or lib64 on your platform. If these flags are used, any
87 krb5-config script is ignored.
89 To specify a particular krb5-config script to use, either set the
90 PATH_KRB5_CONFIG environment variable or pass it to configure like:
92 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
94 To not use krb5-config and force library probing even if there is a
95 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
98 ./configure PATH_KRB5_CONFIG=/nonexistent
100 Similarly, normally configure will use curl-config to determine the
101 flags to use to compile with cURL. If curl-config isn't found, it
102 will look for the standard cURL library in the locations already
103 searched by your compiler. If the curl-config script first in your
104 path is not the one corresponding to the cURL libraries you want to
105 use or if your cURL libraries and includes aren't in a location
106 searched by default by your compiler, you need to specify
107 --with-curl or --with-curl-libs and --with-curl-include as above.
108 Similarly, you can pass CURL_CONFIG to the configure script to change
109 which curl-config script is used.
111 You may optionally build Perl bindings for libwebauth by passing the
112 --enable-perl option to configure. If you do this, whatever version
113 of Perl is found first on your path will be used to build the Perl
114 bindings. You can override this check by setting the environment
115 variable PERL to the full path of the Perl binary that you want to
118 Pass --enable-silent-rules to configure for a quieter build (similar
119 to the Linux kernel).
121 To change the compiler, set the environment variable CC before
122 running configure. Similarly, you can set CFLAGS to whatever
123 compiler flags you wish to build WebAuth with. See:
127 for information about other available options.
129 WebAuth's library will by default be installed in /usr/local/lib, its
130 utility programs will be installed in /usr/local/bin, and its modules
131 will be installed in /usr/local/libexec/apache2/modules. To change
132 those locations, pass the --prefix option to configure with whatever
133 path you want to serve as the installation root. You can use
134 --libexecdir to set the parent directory of the module installation.
135 The modules will be installed in an apache2/modules subdirectory of
138 The install location of the Perl modules will be derived from Perl's
139 configuration and is not affected by --prefix.
141 COMPILING AND TESTING
143 Build WebAuth by running:
147 You can then also run:
151 to have WebAuth build and run some internal consistency checks to make
152 sure that the library functions are working correctly. In order to do
153 more than limited tests of the low-level routines, you should first
154 create a keytab for testing use containing the key for a principal in
155 your local realm. See tests/config/README for instructions on what to
156 create and where to place the files. If you are building the Perl
157 bindings and modules, see perl/t/data/README for instructions about
158 further configuration required to test the WebAuth Perl bindings and
161 If a test case fails, please run the that individual test case with
162 verbose output using:
164 tests/runtests -o <name-of-test>
166 and send the WebAuth maintainers the output when reporting the
171 Install WebAuth with:
175 This will install the shared library, the Apache modules, and
176 optionally the the Perl bindings and WebLogin code as a Perl module.
177 At this point, the software is available but will not be used.
178 Without additional configuration changes to your server, WebAuth is
179 not active and will not protect any web pages.
185 Add Apache directives for WebAuth to your httpd.conf or equivalent
186 file. The basic set of directives are:
188 LoadModule webauth_module \
189 /usr/local/lib/apache2/modules/mod_webauth.so
191 WebAuthKeyringAutoUpdate on
192 WebAuthKeyringKeyLifetime 30d
194 WebAuthLoginURL "https://<your-webkdc>/login/"
195 WebAuthWebKdcURL "https://<your-webkdc>/webkdc-service/"
196 WebAuthWebKdcPrincipal service/webkdc
197 WebAuthKeyring conf/webauth/keyring
198 WebAuthKeytab conf/webauth/keytab
199 WebAuthServiceTokenCache conf/webauth/service_token.cache
201 WebAuthSSLRedirect on
203 In all instances above, replace <your-webkdc> with the hostname of the
204 WebKDC server at your site. conf/sample-webauth.conf contains a
205 heavily-commented version of these directives.
207 If you are testing a beta release, please also add:
210 LogLevel debug # change your existing setting to debug
212 so that your server will generate more complete logs if anything goes
213 wrong. This may also be useful if this is the first time you've
214 installed a WebAuth server.
216 Also, if you are using a self-signed certificate with your WebKDC,
217 you'll need to copy it to a local file (like conf/webauth/webkdc.cert)
218 and add the following directive:
220 WebAuthWebKdcSSLCertFile conf/webauth/webkdc.cert
222 so that the WebAuth Apache module can verify the WebKDC.
226 Make sure that the conf/webauth directory exists:
229 mkdir -p conf/webauth
231 where <apache-root> is the root of your Apache 2.x installation. This
232 directory must be writable by the running web server (and by the child
233 servers, not just the main server), so if you have User and Group
234 directives in your httpd.conf, <apache-root>/conf/webauth should be
235 writable by that user and group.
237 You can put these files somewhere else if you wish. Just change
238 WebAuthKeyring and WebAuthKeytab in your Apache configuration. Only
239 the keyring directory and file need to be writable by the Apache
240 process. The keytab just needs to be readable.
242 Then, install a keytab in <apache-root>/conf/webauth/keytab (or
243 elsewhere if you chose to put it somewhere else). The recommended
244 principal name is webauth/<your-system> where <your-system> is the
245 fully qualified, all-lowercase name of your system. How to obtain a
246 keytab will depend on your local site and how your Kerberos KDC is set
249 After installing the keytab, make sure that it is readable by the user
250 that the web server runs as. (It may have been created only readable
255 Install an SSL certificate for your system, either a self-signed
256 certificate or one signed by whatever certificate authority you
257 normally use. All access to WebAuth-protected web pages must be
258 through SSL to preserve the security of the WebAuth authentication
261 If you have not installed an SSL certificate before, there are
262 instructions available as part of the mod_ssl FAQ. See
263 <http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html#realcert>. Debian
264 users can quickly install a self-signed certificate with the
265 apache2-ssl-certificate utility that comes with the Apache package.
267 If you are using the Debian or Ubuntu Apache packages, you will need
268 to explicitly enable the SSL Apache module with a2enmod ssl. You will
269 then also need to configure the location of your SSL certificate and
270 key file. For Debian and Ubuntu, the best location for the
271 certificate is /etc/ssl/certs, and for the key is /etc/ssl/private.
272 Example configuration:
274 SSLCertificateFile /etc/ssl/certs/<hostname>.pem
275 SSLCertificateKeyFile /etc/ssl/private/<hostname>.key
276 SSLCipherSuite HIGH:MEDIUM:!ADH:!SSLv2:@STRENGTH
277 SSLProtocol all -SSLv2
279 The last two configuration lines disable weak SSL ciphers. You can
280 use similar configuration directives for other operating systems, but
281 may need to change SSLCertificateFile and SSLCertificateKeyFile.
283 See /usr/share/doc/apache2.2-common/README.Debian.gz for more
284 information about configuring SSL on Debian and Ubuntu systems,
285 including how to generate and use self-signed certificates.
287 If your certificate came with intermediate CA certificates, you may
288 need to save them on your system (/etc/ssl/certs is recommended for
289 Debian and Ubuntu systems) and configure that file in Apache as well
292 SSLCertificateChainFile /etc/ssl/certs/<chain-name>.crt
294 replacing <chain-name> with something documenting the intermediate CA
295 certificate chain stored in that file.
299 Restart the server to pick up the configuration changes, and check
300 your error log for any errors indicating a problem with the WebAuth
301 installation. If you are using the default Apache 2.x setup, be sure
302 to start Apache with apachectl startssl to enable SSL.
304 At this point, WebAuth is available to your web server and will be
305 initialized when your server starts, but is not as yet being used to
306 protect any web pages. This can now be configured. For the most
307 basic use of WebAuth, just requiring a valid user login to view a
308 portion of the web pages served out by the server, add the lines:
313 to the <Directory> block for the portion of your web site that you
314 wish to protect. (To restrict access by privilege group, see the
315 instructions below on setting up the LDAP module.)
319 If you want to have your WebAuth server do LDAP directory queries,
320 either to put directory information into environment variables or to
321 use LDAP-based privilege groups for access control, you need to
322 configure the mod_webauthldap module. The basic set of directives
325 LoadModule webauthldap_module \
326 /usr/local/lib/apache2/modules/mod_webauthldap.so
328 WebAuthLdapHost ldap.example.com
329 WebAuthLdapBase dc=example,dc=com
330 WebAuthLdapAuthorizationAttribute privilegegroup
332 WebAuthLdapKeytab conf/webauth/keytab
333 WebAuthLdapTktCache conf/webauth/krb5cc_ldap
335 The first three configuration settings will vary considerably given
336 the name and configuration of your local LDAP server. For more
337 information on what these settings do, see the mod_webauthldap manual.
338 Please note that the WebAuth LDAP module only supports Kerberos
339 GSS-API binds at this time.
341 Once you've added that configuration and restarted Apache, LDAP
342 lookups are available to your web server. This can now be configured.
343 To restrict access to a given set of pages by membership in a
344 privilege group, add the lines:
347 require privgroup example:staff
349 to the <Directory> or <Location> block for the portion of your web
350 site that you wish to protect. example:staff is whatever privilege
351 group you want to use.
353 To put various directory attributes related to the current
354 authenticated user into the environment, additionally add lines like:
356 WebAuthLdapAttribute displayName
357 WebAuthLdapAttribute mail
359 to the <Directory> or <Location> block. The attributes can be any
360 attributes your server has access to read, and the corresponding
361 values from your LDAP server will be put into environment variables of
362 the form WEBAUTH_LDAP_<attribute>, or in this case into the variables
363 WEBAUTH_LDAP_DISPLAYNAME and WEBAUTH_LDAP_MAIL.
365 RUNNING THE MODULE TEST SUITE
367 You can now test WebAuth if you wish (and if this is the first time
368 that you've set up WebAuth, it's recommended). WebAuth comes with a
369 set of test pages that you can use to configure your installation with
370 various different configuration options.
372 To install this test suite, copy (recursively) the files in
373 tests/mod_webauth/conf into your Apache configuration directory and
374 the files in tests/mod_webauth/htdocs under your Apache document root.
376 Now, edit your httpd.conf file and add the line:
378 Include conf/webauth-tests.conf
380 and make sure that the basic WebAuth configuration directives are in
381 your httpd.conf file as described above, or uncomment them in the
382 webauth-tests.conf file.
384 After restarting Apache, you should now be able to go to the URL
385 https://<your-server>/tests/, where <your-server> is the name of your
386 web server, to see the test suite. Documentation on how to walk
387 through all of the tests can be found in doc/test-plan.
391 Congratulations! You have a working WebAuth server. You can now add
392 AuthType WebAuth and require valid-user (or require lines for
393 particular users, or for groups containing user identities as returned
394 by WebAuth) to protect the content served by your web server, and make
395 use of the REMOTE_USER or WEBAUTH_USER environment variables in your
396 CGI scripts. You can also use require privgroup directives and
397 request directory attributes if you have configured the LDAP module as
402 Copyright 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2014
403 The Board of Trustees of the Leland Stanford Junior University
405 Copying and distribution of this file, with or without modification,
406 are permitted in any medium without royalty provided the copyright
407 notice and this notice are preserved. This file is offered as-is,
408 without any warranty.