Distauth: Perl-CGI

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. The following variables may be configured:
    • allow_ucd_ip - allow or disallow UCD IP addresses
    • allowed_nets - IP addresses to allow, if allow_ucd_ip=1;
    • user_list - authorization file to specify a list of authorized users
    • protect_level - security level
    • docs_dir - protected directory location
    • mimetypes - location of mime types file
    • indexfile - default file name
    • doIncludes - do or do not process Apache's server side includes
    • securityext - (for macs only) identify the extension that is used to identify restricted files
    • convert_URLs - (for macs only) use an extension to identify restricted files
    • LogFile - location of the access log file generated by the PERL script
    • passthrough - pass or do not pass the unauthenticated remote_user variable to the middleware
    • auth_sendback - the URL to point at when a cookie doesn't exist or is invalid
    • authdir - location of the security file in AFS space
  2. Figure out the degree of security that your pages require.
  3. 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.
  4. In order to run the script, you must install Perl (minimally, Perl 4.036) on your system. Windows administrators may find the Perl download and installation instructions at the Active State site.
  5. Download the Distributed Authentication service cgi, secure-docs-perl. (The code was updated 2/10/04 to account for the new way that the authentication files are accessed in AFS).

    You will want to change the filename to securedocs.pl (or something along those lines). On UNIX, set the file permissions to rwxr-xr-x (755).
  6. Identify the directory location where your secure documents will be stored. This directory should not be part of your server's primary document directory path.
  7. Identify how you want to trigger running the cgi script.
    • If your server supports a syntax which allows you to identify a secure directory and trigger the running of the secure-docs.pl script (such as Apache), you can use the method described in example 1.
    • Alternatively, you can identify the directory-to-be-secured within the secure-docs.pl script as in example 2. In this case, secure-docs.pl is accessed as a standard cgi script, and only requires a server that supports cgi scripting. This method works with NCSA servers.
  8. Customize the secure-docs.pl file for your site by changing the following variables. Note that there really are few changes that need to be made in most cases.
    1. location of perl: The first line, #! /usr/bin/perl, identifies where perl is located on your system. Change this path accordingly.

      For Windows 2000, a sample path where perl resides on the D drive in the bin directory within the Perl directory is: #!D:/Perl/bin/perl
    2. allow_ucd_ip: Allow IP-based authentication. If you want to allow users within the standard UCD IP domain to access your documents without user-based authentication, set this parameter to 1. If allow_ucd_ip=1; and allowed_nets is set to its default value, IP-based authentication will be in effect for UCD subnets, and user-based authentication will be in effect outside of the ucdavis.edu domain.

      The default value requires user-based authentication: allow_ucd_ip=0
    3. allowed_nets: IP addresses to allow, if allow_ucd_ip=1;
      default value: The UCD Campus and the UCD Medical Center
      @allowed_nets=("128.120.", "169.237.", "152.79.");
    4. user_list: 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's, 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# and 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, @user_list=("/path-to-access-list/list1","/path/list22"); Default value: no authorization file

      #@user_list=("/usr/local/etc/httpd/secure-docs/users"); (The # sign means that the default value is interpreted as a comment).

      In the following sample, a classlist and a local list of TA's will be used for authorization: @user_list=("/afs/ucdavis.edu/common/authclass/199810/eec05.1","/usr/loca l/eec05.extras");

      For current Faculty, Staff and Students

      Unix type systems: @user-list=("/afs/ucdavis.edu/common/authinfo/SFSX");
      Windows Systems (may need to double up the \ if it doesn't work): @user-list=("T:\ucdavis.edu\common\authinfo\SFSX");

      Note, this configuration requires the installation and setup of the AFS client - see above for details. If you don't already have AFS setup and running and decide to use this file, you should upgrade your protect_level to 3 (see next item).
    5. protect_level:
      • Check for presence of cookie ( lowest security and not recommended; protect_level=1).
      • Check that hashed IP address in cookie matches IP address of client. Use this option if your server does not have access to AFS file space. (protect_level=2) We recommend this level for Web servers running on a Macintosh.
      • Check for presence and content of an AFS token file corresponding to the cookie contents (high security, protect_level=3). We highly recommend this option. Default value: $protect_level=3;
    6. docs_dir: docs_dir: protected directory location.

      The use of this variable is dependent upon the Web server that you are using. The most important point is that the document tree for your secure documents should be located outside of your primary document tree. Specifying the document tree with the docs_dir variable is one way of associating the document tree with this cgi. Directions for specific Web servers will differ.

      Apache Web servers: You can specify the docs_dir variable to make use of calling this script through Apache's .htacess files as well, though this is not recommended since if the .htacess file ever disappears, you'll suddenly grant access to your secure documents.

      Macintosh Web servers *must* uncomment and set this variable. Using Macintosh-OS path syntax (with ":" as the separator). For example:
      $docs_dir = "HD:secure-docs";
      default: the docs_dir variable is not specified
      #$docs_dir = "/opt/pkg/apache/secure-docs";
    7. mimetypes: location of mime types file

      This cgi handles all HTTP requests for the secure documents. It must know the location of the mime types file in order to process the HTTP requests to return the correct file type to the user. On Windows 2000, a mimetypes file stored on the C drive in the conf sub-folder of the Apache folders may be:

      $mimetypes = "C:?Program Files/Apache Group/Apache2/conf/mime.types";

      Default: $mimetypes = "/etc/httpd/conf/mime.types";

      Remember to use Macintosh-OS syntax for Macs (":" is the path separator), and Window NT syntax for Windows NT systems ("\" is the path separator). On Windows 2000, we successfully used "/" as the path separator.
    8. indexfile: default file name when a URL is specified as a directory name only

      Most Web servers are configured to accept the file name, index.html, as the default file; some are not. This cgi does not know how your Web server is configured. If a directory is specified in the URL and no file extension is given, this perl script will default to return the contents of the indexfile variable name as the default file name.

      default: Use index.html as the default file name
      $indexfile = "index.html";

      Macintosh users: This parameter setting is ignored.
    9. doIncludes: do or do not process server side includes

      Since this cgi is unaware of the Web server configuration, features such as processing server-side includes are not generally interpreted.

      If $doIncludes=1;, the server will attempt to parse any html comment line containing an Apache-type server side include directive, and include the contents of that file at that place in returned html document. (default value)

      If $doIncludes=0;, include lines are ignored.
    10. LogFile: location of the access log file generated by the PERL script

      If you specify a file name and uncomment the line, the log file will be generated. Log file entries are made whenever the cgi script is called. The format of the file is: DATE USER IPADDRESS ADDRESS FILE. Where:
      DATE - when the script is called
      USER - the UCDLoginID of the user calling the script
      IP ADDRESS - the IP Address of the local browser initiating access to the site
      ADDRESS - the URL directory that is accessed
      FILE - the file within the directory that is accessed


      Example: $LogFile="/opt/apache/log/distauth.log";

      If the line is commented out, the log file will not be generated. Default: The log file is not generated.
      #$LogFile = "/opt/apache/log/distauth.log";

      Note: The specified file must be writable by the Web server. If the Web server runs as a certain user such as httpd, this user must have permission to write to the file.
    11. pass-through: 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 the use of pass-through="true". pass-through="true" 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="true". By setting pass-through="true", 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.

      In reality, the value of the pass-through variable is not checked; it is only checked to see if it is present, so setting it to "false" or "no" will still result in a true statement.
    12. authdir: Specify the AFS directory that your server will be reading.

      For unix systems, use the default setting: $authdir = "/afs/ucdavis.edu/common/authinfo";

      For windows NT systems use the setting corresponding to the drive where AFS is mounted. For example: $authdir = "T:/ucdavis.edu/common/authinfo";
    13. auth_sendback: If no cookie is set in the user's browser, the local Web server will redirect it to the Web page identified by auth_sendback.

      We recommend using the following option. It provides a Web page of user documentation during the user authentication process before displaying the user name and password dialog box: $auth_sendback = "http://www.ucdavis.edu/cgi-bin/sendback-with-docs";

      The following option does not provide a document page before prompting for the UCDLoginID and Kerberos Password: $auth_sendback = "https://securedocs.ucdavis.edu/cgi-auth/sendback";
    14. convert_URLs:(Macs only) use an extension to identify restricted files options:

      $convert_URLs=0;
      Do not convert URLs automatically based on the security extension.

      $convert_URLs=1;
      This script will add and delete the security extension automatically for any document in the directory identified by the docs_dir variable.
    15. securitytext:(Macs only) identify the extension that is used to recognize restricted files

      To set the extension to the recommended default, $securityext = ".sec";

      If you prefer a different extension, this is your chance to specify it.
  9. Place the secure-docs.pl script in the cgi directory.