Skip directly to: News, Events, and Quick Links

Distauth: Instructions for the iPlanet/SunOne Enterprise Server

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: allow access to the following IP addresses without user authentication
    • deny: deny access to the following IP addresses
    • useafs: high level security using cookie and AFS file
    • user-list: Only allow access to a specific set of users who are listed in a file(s) identified by this variable. See here for current Student, Faculty and Staff configuration
    • pass-through: a token to indicate the server should only check the validity of the cookie but still allow the user through, leaving authorization issues up to a middleware application. As usual, the REMOTE_USER CGI environmental variable will be set to the UCDLoginID of the user, if the user successfully authenticates.
    • afsdirectory: location of security file in AFS space
    • cookie-set-url: the URL to point at when a cookie doesn't exist or is invalid
  2. If you plan to enable the recommended level of security where the script will verify that the cookie and related AFS file are in agreement, 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.
  3. Download the file that matches your operating system and iPlanet/Netscape version.

    If the server version/OS that you need is not in this list, you can request it by sending an email message to distauth&ucdavis.edu. We will compile a version for your operating system and iPlanet/Netscape version.
  4. For unix installations, name the file "auth-client.so". You can place this file in any location. For example, our file was written to: "/obj/pkg/ns-home/suitespot/nsapi/UCD/auth-client.so"

    For Windows NT/2000 installations, name the file "auth-client.dll".
  5. The ServerName must be fully qualified. This field is often found in the magnus.conf file. In iPlanet version 6 for Windows 2000, the ServerName field that is used by the program is the one that is located in the server.xml file.
  6. The following configuration information is generally located in the obj.conf file. In iPlanet version 6 for Windows 2000, the init lines are placed in the magnus.conf file, and the remaining lines are placed in the obj.conf file.
  7. Make a backup copy of your iPlanet/Netscape server’s obj.conf file, located in your iPlanet/Netscape server's config subdirectory.
  8. Configure your server's obj.conf file. (It is not possible to make all of these additions to the file through the use of the administration server's interface.)
    1. Read through the obj.conf example file as the following changes are explained. The important lines are marked in bold.
    2. The cookie authentication function that is going to be used later on in the file needs to be loaded, so the following line needs to be put at the top of the obj.conf file with the other Init functions:

      Init fn="load-modules" shlib="/PATH/TO/LIB/auth-client.so" funcs="client_cookie_auth"

      Note: The library can exist anywhere in the file space of the server. Also, this single line is displayed as two lines in this example, though it must really be a continuous line in your obj.conf file.
    3. Map the object style to a physical directory. In the example obj.conf file, the line:

      NameTrans fn=pfx2dir from=/secure-docs dir="/opt/pkg/ns-home/suitespot/secure- docs" name="secure-docs"

      maps the object named secure-docs to a directory called secure-docs, located at /opt/pkg/ns-home/suitespot/secure-docs.

      Note that this line must occur BEFORE the NameTrans line for the document root.

      In this scenario, any document placed in the directory, /opt/pkg/ns-home/suitespot/secure-docs, would be secure. We recommend that you place documents that are to be secured outside of the document root where your unrestricted documents are located.
    4. The server must be told how to restrict access to the directories that you have defined. In other words, here is your opportunity to customize the action of the script. This can be done via an Object section call:

      <Object name="secure-docs">

      (where obj_name has been defined by a NameTrans declaration in the previous step.) Here is a sample object definition:

      <Object name="secure-docs">PathCheck fn="client_cookie_auth" useafs="true"</Object>

      client_cookie_authis the name routine that checks to see if the cookie is valid and if not passes the user to the secure Kerberos authentication server. This function name is required.

      Here is a summary of the of the options that may be configured in PathCheck line.
      • cookie-set-url: If no cookie is set in the user’s browser, the local Web server will redirect it to the Web page identified by cookie-set-url. 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.

        cookie-set-url="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: cookie-set-url="https://secureWeb.ucdavis.edu/cgi-auth/sendback"

        If cookie-set-url is not specified, the default behavior will be the same as: cookie-set-url="http://www.ucdavis.edu/cgi-bin/sendback-with-docs"
      • useafs = "true": a variable to indicate the server should check the cookie against the contents of the token file in AFS space. This should be set to true for servers with access to AFS space. If the afsdirectory variable is present as well, useafs is assumed to be true and does not need to be specified.

        In reality, the value of the useafs 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.

        If you are not using the AFS file check, delete this option.
      • afsdirectory = "/afs/ucdavis.edu/common/authinfo": Indicates the path to the afs directory containing the token files writen by the campus server in charge of generating the cookies. If useafs=true is specified and the afsdirectory variable is not, the path is assumed to be "/afs/ucdavis.edu/common/authinfo" for unix systems and "T:/ucdavis.edu/common/authinfo" for NT systems.

        If you are not using the AFS file check, delete this option.
      • allow: Allow access to any specified subnet without user-based authentication. For instance, allow=128.120,169.237

        The browers on subnets, 128.120.x.x and 169.237.x.x, would be allowed access to the secured directory, with no user authentication required. Do not add any whitespace to this statement. By default, user-based authentication is required unless this allow is specified.
      • deny: Deny access to any specified subnet, and do not allow user-based authentication from these subnets. These browsers will be redirected to our error screen. For instance, deny=128.120.1.1,128.120.57

        The browsers located at 128.120.1.1 and 128.120.57.x will not be allowed access to the secured directory. The deny list overrides the allow list. Note: Do not add any whitespace to this statement.
      • user-list: Once a user has authenticated, an additional authorization step will be performed before the user is allowed access to the Web page. The useršs UCDLoginID, the same name used in the authentication step, must also appear in one of the files specified by the user-list variable. For example: user-list=/path/to/access-list,/path/to/another-access-file

        The file(s) specified by this option should contain list(s) of users, with one user on each line of the file.

        Note: It would not make sense to use the variable, allow, and the variable, user-list in the same script, since IP-based authentication is not compatible with authorization.

        For current Faculty, Staff, Students

        Unix: user-list=/afs/ucdavis.edu/common/authinfo/SFSX

        Windows (may need to double up the \ if it doesn't work): user-list=T:\ucdavis.edu\common\authinfo\SFSX

        Use of this method requires the installation of an AFS client, please see above. If you are not already doing so, you should probably also configure the AFS file checking option for the most secure version of Distauth - See useafs.
      • pass-through = "true": 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.
    5. Restart your server.
    6. Netscape provides the UCDLoginID, site, and date as part of its standard log. If you require this type of record, view Netscape's error log.

Usage in CGI Scripts

To utilize the security in a CGI script, the object definition is defined as a CGI object as the following example shows:

     <Object name="secure-cgi">
          Pathcheck fn="client_cookie_auth" userdb="garbage"
          cookie-set-url="http://www.ucdavis.edu/cgi-bin/sendback-with-docs"
          useafs="true"
          ObjectType fn="force-type" type="magnus-internal/cgi"
          Service fn="send-cgi"
     </Object>

After the authentication has been checked by the client_cookie_auth routine, the CGI script is executed by the object type and service definition following the PathCheck line. The CGI script's environment will include the environmental variable "REMOTE_USER", which will be set to the user's UCD LoginID.