Distauth: Apache Instructions

Instructions

  1. Read the section, Local Web Service Evaluation, and determine the degree of security that your pages require as well as the authorization and authentication features that apply to your project.
  2. Get and install the Apache Web Server, Perl, and the Apache mod_perl plugin. Windows users may want to grab a copy of everything you need in one package from here.

    This document will not describe how to setup or configure Apache itself, so please refer to the Apache Documentation for how to install, configure, and run your Apache Web Server.

    By default, Apache isn't configured to use mod_perl. To do this, after you have installed both, you typically have to add lines that say something like into your httpd.conf file:

    LoadModule perl_module   modules/libperl.so
    AddModule mod_perl.c

    This will greatly depend on your installation, so please refer to the Apache Documentation and the mod_perl Web page to learn how to install and configure it properly for your system.
  3. Grab the appropriate DistAuth.pm module and place the module into a path that Apache and mod_perl were configured to look in. Typically, you would put it in a directory like ~www/lib/perl/Apache/DistAuth.pm, but that may differ from installation to installation.

    Under a RedHat Linux rpm-installed apache and mod_perl, it should go into /etc/httpd/lib/perl/Apache/DistAuth.pm

    Under Windows32, it should probably go into C:/Apache/lib/perl/Apache/DistAuth.pm but could be anywhere, depending on version of Apache and how it was built. You will more than likely need to make the Apache directory and then place the DistAuth.pm file in it. If you are having problems finding where to put it, try making the Apache directory at the Apache ServerRoot Location.

    Note: Some of the directories referenced above may not exist yet, so you'll have to create them.
  4. In your httpd.conf file, add the following line at the bottom:
    PerlModule Apache::DistAuth
  5. In any apache .conf file, such as your access.conf file, protect the directories you want to protect using an Apache directive like the following, where secure-docs is an arbitrary name and could be replaced with whatever directory or alias you would like to use:

    Alias /secure-docs/path/to/securedocs
    <Location /secure-docs>
        PerlAccessHandler Apache::DistAuth
        PerlSetVar protection_level 2
    </Location>
  6. Apache 2 needs the following line included in the Location directive: PerlOptions +GlobalRequest
  7. Configure it further by adding more valid PerlSetVar directives like the "protection_level" example above by using the directives found below. The lines must all begin with PerlSetVar and are followed by a configuration token and its value. If the value you want contains spaces or multiple words, then it needs to be included inside quotation marks.
    1. Figure out the degree of security that your pages require and set the protection_level variable to it. Protection_level NUM values:
          1 - Check for presence of cookie (not recommended, very weak security)
          2 - Check that hashed IP address in cookie matches IP address of client
          3 - Check for pressnce of AFS flag file and that data matches (DEFAULT)
    2. If you plan to enable the highest level of security, install AFS. In addition, send a message to afs-setup@ucdavis.edu, requesting that your Web server be given read access to the AFS authentication directory. Include the IP address of your Web server in your message.
    3. afs_auth_directory DIRECTORY_LOCATION

      This should only need changing on a win32 system. It defaults to "/afs/ucdavis.edu/common/authinfo" which should be correct on any unix system.

      For windows NT systems use the setting corresponding to the drive where AFS is mounted. For example,

      afs_auth_directory T:/ucdavis.edu/common/authinfo

      default: /afs/ucdavis.edu/common/authinfo
    4. authenticator_url SEND_CLIENTS_TO_URL

      You have three choices for this value:
          1 - Default: http://www.ucdavis.edu/cgi-bin/sendback-with-docs
          2 - No docs: https://secureWeb.ucdavis.edu:443/cgi-auth/sendback
          3 - Form-based: https://secureWeb.ucdavis.edu:443/form-auth/sendback
    5. user_list "FILE1, FILE2, ..."

      Only allow access to a specific set of users who are listed in a file(s) identified by this variable.

      The content of a file in user_list is UCDLoginID’, one per line. Files containing the UCDLoginID’s of the students assigned to a particular class are updated nightly and stored at /afs/ucdavis.edu/common/authclass/Banner_quarter_or_semester_code.

      The classlist file names are in the format: three_letter_dept_course_#.section#

      You must apply to be a member of a highly restricted group in order to read these classlists. In addition, the Web server that is used must be a secure system with only sys admin access.

      Options: include one or more files in the format, "/path-to-access-list/list1, /path/list22"

      Default value: No authorization file.

      A list of files that should contain campus login names for the people you want this site restricted to. With this directive in place, only the people found in this file will be allow to see the contents of the page in question.

      Default: Anyone with a valid UCDLoginID can see the pages. note: add configuration lines below to limit to current UC Davis affiliates and restrict prospective students.

      For current Faculty, Staff and Students

      UNIX: PerlSetVar user_list = /afs/ucdavis.edu/common/authinfo/SFSX
      Windows (double up the \ if it doesn't work): PerlSetVar user_list = T:\ucdavis.edu\common\authinfo\SFSX

      Note: Use of the above requires the installation and configuration of the AFS client (see above). If you're not already using AFS and decide to install the client for this method, you should also implement the highest protection_level
    6. pass_through 1

      The default behavior of this script is to refuse access to a user who cannot pass the authentication step. However, this behavior may be overridden by setting use of this pass-through variable. Setting pass_through to 1 indicates that the Web server should check the validity of the cookie and set the REMOTE_USER CGI environmental variable, and allow access to all users, regardless of their ability to pass the authentication step. Browsers without a valid Distributed Authentication cookie will still be allowed access, but the REMOTE_USER CGI enviornmental will not be set. If you are using middleware such as Cold Fusion, and if the underlying database contains restricted and unrestricted data, set pass_through to 1. By setting setting it to 1, the user will be authenticated, if possible. However, even if the user is not authenticated, the middleware can be programmed to decide what information to present to the end user based on the REMOTE_USER environmental variable.
    7. allow_ucd_ip 1

      This will allow ucd specific IP Addresses through without having authenticated with their kerberos password first. default: off (0).
    8. allow_ucd_ip_addrs 169.237.,128.120.,152.79

      This allows you to override the default list of ipaddresses that are considered to be on campus and accepted without authentication when the allow_ucd_ip variable is set to 1 (see above).

      Note: You should make sure the trailing period is in place for proper subnet checks, otherwise 152.12 will match 152.12 *and* 152.120, 152.121...

      Default: 169.237.,128.120.,152.79
    9. logout_interval 43200

      This will force the user to reauthenticate after the given interval, in seconds. The default is 43200 (12 hours).
  8. Don't forget to restart apache any time you modify the defaults you set in your apache .conf files. Typically you can do this by running apachectl restart on your server.