WebAuth Installation Instructions

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.

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. It also requires MIT Kerberos v5, 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.

When building Apache 2.x, 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).
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.63 and Automake 1.10 or later are required.
Run configure. The command will look something like:
```
    ./configure --with-apache=/usr/local/apache2 \
        --with-kerberos=/usr/local --with-openssl=/usr/local \
        --with-curl=/usr/local --with-ldap=/usr/local
```
Adjust the paths to match where you have installed those packages. You can omit --with-kerberos, --with-openssl, --with-curl, 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-apache if the right version of apxs is in your path; otherwise, apxs should be in a bin subdirectory of the path that you give to --with-apache. If your Apache installation doesn't have a single root directory (if you are, for example, using the Apache package installed from a Linux distribution), you can instead specify the full path to apxs with --with-apxs instead of --with-apache.

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.

configure will detect various things about your system and will generate the makefiles and include files required to build WebAuth.

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 and its utility programs will be installed in /usr/local/bin; to change those locations, pass the --prefix option to configure with whatever path you want to serve as the installation root. The install location of the Apache modules will be determined by Apache's apxs utility, and the install location of the Perl modules will be derived from Perl's configuration; neither are 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.
Install WebAuth with:
```
    make install
```
This will install the shared library, use apxs to install the Apache modules, and install the Perl bindings 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. Stanford users should simply copy conf/stanford-webauth.conf to their Apache 2.x conf directory and then add the line:
```
    Include conf/stanford-webauth.conf
```
to their httpd.conf file. For users at other sites, the basic set of directives are:
```
    LoadModule webauth_module 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.

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 v3 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
```
This is not needed when using Stanford's 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 needs to be writable by the Apache process. The keytab just needs to be readable.
Install a keytab in <apache-root>/conf/webauth/keytab. The recommended principal name is webauth/<your-system> where <your-system> is the fully qualified, all-lowercase name of your system. For example, if you were installing WebAuth on a system named app-server at Stanford, the recommended principal name is webauth/app-server.stanford.edu. (Note that at Stanford, other principals may not work.)

Stanford users can create a WebAuth keytab for a server with:
```
    wallet -f <apache-root>/conf/webauth/keytab get keytab \
        webauth/<your-system>.stanford.edu
```
replacing <apache-root> and <your-system> as above. You must already be authenticated as a user, administrator, or admin team member for the system, as set up in NetDB. For more information, see:
```
    http://www.stanford.edu/services/kerberos/sysadmin/wallet.html
```
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.

Stanford users, for university applications, can obtain one of the SSL certificates the university has licensed from a certificate vendor. There is a fee to offset the licensing charge. For more information, see <http://www.stanford.edu/services/ssl/>. This is only for Stanford users.
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.)
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.
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. Stanford users should simply copy conf/stanford-ldap.conf to their Apache 2.x conf directory and then add the line:
```
    Include conf/stanford-ldap.conf
```
to their httpd.conf file. Stanford users will also need to submit a HelpSU ticket to be added to the ACLs on the directory servers. See <http://www.stanford.edu/services/directory/access/> for more information.

For users at other sites, the basic set of directives are:
```
    LoadModule webauthldap_module 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 settings will vary considerably given the name and configuration of your local LDAP server. For more information on what these attributes do, see the mod_webauthldap manual. Please note that the WebAuth LDAP module only supports Kerberos v5 GSS-API binds at this time.
At this point, 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.
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.

Converted to XHTML by faq2html version 1.28