| Russ Allbery > Software > Orphaned Software > WebAuth | WebAuth at Stanford > |
These installation instructions are for the typical WebAuth user who wants to set up a web server with content protected by WebAuth and take advantage of an existing site WebAuth infrastructure (including a login server and WebKDC). For details on how to install the site infrastructure, which is more complex and only has to be done once at each site, see doc/install-webkdc.
If you have installed the Debian or Ubuntu packages, please see /usr/share/doc/libapache2-webauth/README.Debian.gz, which is more complete and specific for using those packages than these instructions.
Make sure that you have all of the required packages installed. WebAuth is implemented as Apache 2.x modules, and therefore requires an installation of Apache 2.0.43 or later built with SSL and dynamic modules. There are reports of problems with Apache 2.0.x as shipped with Solaris 10 x86, so Apache 2.2 or later is recommended. It also requires Kerberos, cURL, and OpenSSL 0.9.7 or later (for AES support). See README for more version dependencies.
In order to build the LDAP module, Cyrus SASL 2.x and OpenLDAP are also required.
Note that all of these packages should be installed on local disk. We do not recommend using libraries installed on shared file systems such as AFS, since the reliability of your web server will then be tied to the availability of that remote file system. The required libraries aren't large, particularly given the average size of modern disks.
If you build your own Apache 2.x server, you'll want to use a configure invocation like:
./configure --enable-so --enable-ssl --with-ssl=/usr/local
(changing the last if your OpenSSL is installed somewhere else). Any pre-packaged Apache server should be built this way.
If you are building a Git clone of the WebAuth distribution (as opposed to a packaged release, which already includes the generated configure script), cd to the top of the source tree and run:
./autogen
to generate the configure script. Autoconf 2.64 and Automake 1.11 or later are required, Perl is required to generate the man pages, and xml2rfc is required to build the protocol documentation.
Run configure. The command will look something like:
./configure --with-apxs=/usr/local/apache2/bin/apxs \
--with-openssl=/usr/local --with-ldap=/usr/local
configure will detect various things about your system and will generate the makefiles and include files required to build WebAuth.
Adjust the paths to match where you have installed those packages. You can omit --with-openssl and --with-ldap if the packages are installed in locations automatically searched by your compiler and linker (which will be the case if you're using Linux and the packages that come with your Linux distribution).
You can omit --with-apxs if the right version of apxs is in your path.
Normally, configure will use krb5-config to determine the flags to use to compile with your Kerberos GSS-API libraries. If krb5-config isn't found, it will look for the standard Kerberos libraries in locations already searched by your compiler. If the krb5-config script first in your path is not the one corresponding to the Kerberos libraries you want to use or if your Kerberos libraries and includes aren't in a location searched by default by your compiler, you need to specify --with-krb5=PATH:
./configure --with-krb5=/usr/local
You can also individually set the paths to the include directory and the library directory with --with-krb5-include and --with-krb5-lib. You may need to do this if Autoconf can't figure out whether to use lib, lib32, or lib64 on your platform. If these flags are used, any krb5-config script is ignored.
To specify a particular krb5-config script to use, either set the PATH_KRB5_CONFIG environment variable or pass it to configure like:
./configure PATH_KRB5_CONFIG=/path/to/krb5-config
To not use krb5-config and force library probing even if there is a krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent path:
./configure PATH_KRB5_CONFIG=/nonexistent
Similarly, normally configure will use curl-config to determine the flags to use to compile with cURL. If curl-config isn't found, it will look for the standard cURL library in the locations already searched by your compiler. If the curl-config script first in your path is not the one corresponding to the cURL libraries you want to use or if your cURL libraries and includes aren't in a location searched by default by your compiler, you need to specify --with-curl or --with-curl-libs and --with-curl-include as above. Similarly, you can pass CURL_CONFIG to the configure script to change which curl-config script is used.
You may optionally build Perl bindings for libwebauth by passing the --enable-perl option to configure. If you do this, whatever version of Perl is found first on your path will be used to build the Perl bindings. You can override this check by setting the environment variable PERL to the full path of the Perl binary that you want to use.
Pass --enable-silent-rules to configure for a quieter build (similar to the Linux kernel).
To change the compiler, set the environment variable CC before running configure. Similarly, you can set CFLAGS to whatever compiler flags you wish to build WebAuth with. See:
./configure --help
for information about other available options.
WebAuth's library will by default be installed in /usr/local/lib, its utility programs will be installed in /usr/local/bin, and its modules will be installed in /usr/local/libexec/apache2/modules. To change those locations, pass the --prefix option to configure with whatever path you want to serve as the installation root. You can use --libexecdir to set the parent directory of the module installation. The modules will be installed in an apache2/modules subdirectory of that directory.
The install location of the Perl modules will be derived from Perl's configuration and is not affected by --prefix.
Build WebAuth by running:
make
You can then also run:
make check
to have WebAuth build and run some internal consistency checks to make sure that the library functions are working correctly. In order to do more than limited tests of the low-level routines, you should first create a keytab for testing use containing the key for a principal in your local realm. See tests/config/README for instructions on what to create and where to place the files. If you are building the Perl bindings and modules, see perl/t/data/README for instructions about further configuration required to test the WebAuth Perl bindings and WebLogin code.
If a test case fails, please run the that individual test case with verbose output using:
tests/runtests -o <name-of-test>
and send the WebAuth maintainers the output when reporting the problem.
Install WebAuth with:
make install
This will install the shared library, the Apache modules, and optionally the the Perl bindings and WebLogin code as a Perl module. At this point, the software is available but will not be used. Without additional configuration changes to your server, WebAuth is not active and will not protect any web pages.
Add Apache directives for WebAuth to your httpd.conf or equivalent file. The basic set of directives are:
LoadModule webauth_module \
/usr/local/lib/apache2/modules/mod_webauth.so
WebAuthKeyringAutoUpdate on
WebAuthKeyringKeyLifetime 30d
WebAuthLoginURL "https://<your-webkdc>/login/"
WebAuthWebKdcURL "https://<your-webkdc>/webkdc-service/"
WebAuthWebKdcPrincipal service/webkdc
WebAuthKeyring conf/webauth/keyring
WebAuthKeytab conf/webauth/keytab
WebAuthServiceTokenCache conf/webauth/service_token.cache
WebAuthSSLRedirect on
In all instances above, replace <your-webkdc> with the hostname of the WebKDC server at your site. conf/sample-webauth.conf contains a heavily-commented version of these directives.
If you are testing a beta release, please also add:
WebAuthDebug on
LogLevel debug # change your existing setting to debug
so that your server will generate more complete logs if anything goes wrong. This may also be useful if this is the first time you've installed a WebAuth server.
Also, if you are using a self-signed certificate with your WebKDC, you'll need to copy it to a local file (like conf/webauth/webkdc.cert) and add the following directive:
WebAuthWebKdcSSLCertFile conf/webauth/webkdc.cert
so that the WebAuth Apache module can verify the WebKDC.
Make sure that the conf/webauth directory exists:
cd <apache-root>
mkdir -p conf/webauth
where <apache-root> is the root of your Apache 2.x installation. This directory must be writable by the running web server (and by the child servers, not just the main server), so if you have User and Group directives in your httpd.conf, <apache-root>/conf/webauth should be writable by that user and group.
You can put these files somewhere else if you wish. Just change WebAuthKeyring and WebAuthKeytab in your Apache configuration. Only the keyring directory and file need to be writable by the Apache process. The keytab just needs to be readable.
Then, install a keytab in <apache-root>/conf/webauth/keytab (or elsewhere if you chose to put it somewhere else). The recommended principal name is webauth/<your-system> where <your-system> is the fully qualified, all-lowercase name of your system. How to obtain a keytab will depend on your local site and how your Kerberos KDC is set up.
After installing the keytab, make sure that it is readable by the user that the web server runs as. (It may have been created only readable by root.)
Install an SSL certificate for your system, either a self-signed certificate or one signed by whatever certificate authority you normally use. All access to WebAuth-protected web pages must be through SSL to preserve the security of the WebAuth authentication tokens.
If you have not installed an SSL certificate before, there are instructions available as part of the mod_ssl FAQ. See <http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html#realcert>. Debian users can quickly install a self-signed certificate with the apache2-ssl-certificate utility that comes with the Apache package.
If you are using the Debian or Ubuntu Apache packages, you will need to explicitly enable the SSL Apache module with a2enmod ssl. You will then also need to configure the location of your SSL certificate and key file. For Debian and Ubuntu, the best location for the certificate is /etc/ssl/certs, and for the key is /etc/ssl/private. Example configuration:
SSLCertificateFile /etc/ssl/certs/<hostname>.pem SSLCertificateKeyFile /etc/ssl/private/<hostname>.key SSLCipherSuite HIGH:MEDIUM:!ADH:!SSLv2:@STRENGTH SSLProtocol all -SSLv2
The last two configuration lines disable weak SSL ciphers. You can use similar configuration directives for other operating systems, but may need to change SSLCertificateFile and SSLCertificateKeyFile.
See /usr/share/doc/apache2.2-common/README.Debian.gz for more information about configuring SSL on Debian and Ubuntu systems, including how to generate and use self-signed certificates.
If your certificate came with intermediate CA certificates, you may need to save them on your system (/etc/ssl/certs is recommended for Debian and Ubuntu systems) and configure that file in Apache as well with:
SSLCertificateChainFile /etc/ssl/certs/<chain-name>.crt
replacing <chain-name> with something documenting the intermediate CA certificate chain stored in that file.
Restart the server to pick up the configuration changes, and check your error log for any errors indicating a problem with the WebAuth installation. If you are using the default Apache 2.x setup, be sure to start Apache with apachectl startssl to enable SSL.
At this point, WebAuth is available to your web server and will be initialized when your server starts, but is not as yet being used to protect any web pages. This can now be configured. For the most basic use of WebAuth, just requiring a valid user login to view a portion of the web pages served out by the server, add the lines:
AuthType WebAuth
require valid-user
to the <Directory> block for the portion of your web site that you wish to protect. (To restrict access by privilege group, see the instructions below on setting up the LDAP module.)
If you want to have your WebAuth server do LDAP directory queries, either to put directory information into environment variables or to use LDAP-based privilege groups for access control, you need to configure the mod_webauthldap module. The basic set of directives are:
LoadModule webauthldap_module \
/usr/local/lib/apache2/modules/mod_webauthldap.so
WebAuthLdapHost ldap.example.com
WebAuthLdapBase dc=example,dc=com
WebAuthLdapAuthorizationAttribute privilegegroup
WebAuthLdapKeytab conf/webauth/keytab
WebAuthLdapTktCache conf/webauth/krb5cc_ldap
The first three configuration settings will vary considerably given the name and configuration of your local LDAP server. For more information on what these settings do, see the mod_webauthldap manual. Please note that the WebAuth LDAP module only supports Kerberos GSS-API binds at this time.
Once you've added that configuration and restarted Apache, LDAP lookups are available to your web server. This can now be configured. To restrict access to a given set of pages by membership in a privilege group, add the lines:
AuthType WebAuth
require privgroup example:staff
to the <Directory> or <Location> block for the portion of your web site that you wish to protect. example:staff is whatever privilege group you want to use.
To put various directory attributes related to the current authenticated user into the environment, additionally add lines like:
WebAuthLdapAttribute displayName
WebAuthLdapAttribute mail
to the <Directory> or <Location> block. The attributes can be any attributes your server has access to read, and the corresponding values from your LDAP server will be put into environment variables of the form WEBAUTH_LDAP_<attribute>, or in this case into the variables WEBAUTH_LDAP_DISPLAYNAME and WEBAUTH_LDAP_MAIL.
You can now test WebAuth if you wish (and if this is the first time that you've set up WebAuth, it's recommended). WebAuth comes with a set of test pages that you can use to configure your installation with various different configuration options.
To install this test suite, copy (recursively) the files in tests/mod_webauth/conf into your Apache configuration directory and the files in tests/mod_webauth/htdocs under your Apache document root.
Now, edit your httpd.conf file and add the line:
Include conf/webauth-tests.conf
and make sure that the basic WebAuth configuration directives are in your httpd.conf file as described above, or uncomment them in the webauth-tests.conf file.
After restarting Apache, you should now be able to go to the URL https://<your-server>/tests/, where <your-server> is the name of your web server, to see the test suite. Documentation on how to walk through all of the tests can be found in doc/test-plan.
Congratulations! You have a working WebAuth server. You can now add AuthType WebAuth and require valid-user (or require lines for particular users, or for groups containing user identities as returned by WebAuth) to protect the content served by your web server, and make use of the REMOTE_USER or WEBAUTH_USER environment variables in your CGI scripts. You can also use require privgroup directives and request directory attributes if you have configured the LDAP module as well.
The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
| Russ Allbery > Software > Orphaned Software > WebAuth | WebAuth at Stanford > |