                    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.

 1.  Make sure that you have all of the required packages installed.
     WebAuth is implemented as Apache 2.0 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.0, 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).

     Stanford users who are building Apache with GCC from pubsw should
     beware that Apache's build system tends to pick up Berkeley DB 4.0,
     zlib, and GDBM from pubsw, and that you'll therefore need those
     shared libraries available (preferrably on local disk) for the
     resulting Apache 2.0 server to run.

 2.  If you are building a CVS pull 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.57 or later is
     required.

 3.  Run configure.  The command will look something like:

         ./configure --with-apache=/usr/local/apache2 \
             --with-krb5=/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-krb5, --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, and the --with-apache
     option should point to the directory above your htdocs directory (and
     will only be used for installing the test suite, if you choose to do
     that).

     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.

 4.  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.

 5.  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.

 6.  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.0 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.

 7.  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.0 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.

 8.  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 request a keytab be created for their system by
     sending mail to srvtab-request@stanford.edu, specifying the SUNet ID
     that should be able to download the keytab.  The keytab can then be
     downloaded with the command:

         /usr/pubsw/sbin/leland_srvtab \
             -f <apache-root>/conf/webauth/srvtab \
             -k <apache-root>/conf/webauth/keytab \
             webauth.<your-system>

     replacing <apache-root> and <your-system> as above, except in this
     case, <your-system> should *not* be fully qualified (it should be
     just the system name without .stanford.edu).  Note that Stanford's
     current keytab download system doesn't allow a keytab to be
     downloaded without simultaneously downloading a srvtab, but the
     resulting conf/webauth/srvtab file is not used by WebAuth and can be
     deleted after leland_srvtab is run.

     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.)

 9.  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.0/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.

10.  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.0 setup, be
     sure to start Apache with apachectl startssl to enable SSL.

11.  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.)

12.  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, run:

         make install-tests

     The tests will be installed in htdocs/tests under the path that you
     gave to WebAuth's --with-apache configure option.  A configuration
     fragment will also be installed in conf/webauth-tests.conf.

     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.

13.  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.0 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.

14.  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.

15.  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.
