DLXS Authentication and Authorization System

From DLXS Documentation

(Difference between revisions)
Jump to: navigation, search
Current revision (10:11, 5 July 2016) (edit) (undo)
m (→Example: Permitting an institution to a collection)
 
(26 intermediate revisions not shown.)
Line 1: Line 1:
 +
[[DLXS Wiki|Main Page]] > [[Ancillary Resources]] > DLXS Authentication and Authorization System
 +
==Functional overview==
==Functional overview==
-
<p>The DLXS Authentication and Authorization system is a complete access control
 
-
  system designed primarily for use in digital library environments. It can
 
-
  interoperate with core DLXS middleware to control access to collections, or
 
-
  it can be used as a standalone access control system in a general web environment.</p>
 
-
<p>The system has the following general capabilities:
+
The DLXS Authentication and Authorization system is a complete access control system designed primarily for use in digital library environments. It can interoperate with core DLXS middleware to control access to collections, or it can be used as a standalone access control system in a general web environment.
-
<ul>
+
-
  <li>user authentication, using either a self-contained encrypted password
+
-
      or existing Kerberos authentication server(s)</li>
+
-
  <li>user self-service: each user can set or reset his/her password, and will
+
-
      receive automated confirmation email after doing so</li>
+
-
  <li>institutional authentication using IP address ranges</li>
+
-
  <li>centralized management of all user, institution, and access information
+
-
      in an Oracle database</li>
+
-
</ul>
+
-
</P>
+
-
<p>Designed to function with a heterogenous mix of resources, both public and
+
-
  restricted, this system could be useful if you are looking to do any of the
+
-
  following:
+
-
<ul>
+
The system has the following general capabilities:
-
  <li>provide off-campus users with authenticated access to locally-hosted resources</li>
+
-
  <li>leverage an existing Kerberos authentication infrastructure in a web environment</li>
+
-
  <li>provide other institutions with IP address range-based access to locally-hosted
+
-
      resources</li>
+
-
</ul>
+
-
</P>
+
-
==Technical overview==
+
-
<p>The system is made up of three components:  
+
-
<ol>
+
-
<li>authentication and authorization database: Here is stored all information
+
-
  on user accounts and user groups, institution names and IP address ranges,
+
-
  collections or resources, and access permissions--which users and institutions
+
-
  may access which collections or resources. This must be an Oracle database.</li>
+
-
<li>Apache web server module: This modular extension to Apache acts as a gatekeeper
+
* user authentication, using either a self-contained encrypted password or existing Kerberos authentication server(s)
-
  to all of the material on the web server, consulting the database in real
+
* user self-service: each user can set or reset his/her password, and will receive automated confirmation email after doing so
-
  time. It uses the access control information in the database to grant access,
+
* institutional authentication using IP address ranges
-
  deny access, or request authentication. In addition, it implements the user
+
* centralized management of all user, institution, and access information in an Oracle database
-
  interface which accepts a username and password, or which guides new users
+
-
  through the process of setting their initial password.</li>
+
-
<li>Page templates: The Apache module uses these fully-customizable HTML templates
+
-
  to generate the pages in the user interface.</li>
+
-
</ol>
+
-
==Requirements==
+
Designed to function with a heterogenous mix of resources, both public and restricted, this system could be useful if you are looking to do any of the following:
-
<p> This is a robust system that supplies a complete campus authentication and
+
-
  authorization environment, and as such, it has heavy requirements that may
+
-
  be out of reach for some institutions or impractical for some purposes. DLXS
+
-
  acknowledges this, and will also be undertaking development of a "Lite" version
+
-
  of this system that requires nothing beyond the [../intro/sysreq.html standard
+
-
  DLXS system requirements]. This product is currently being shaped, but
+
-
  will probably be geared strictly toward interoperation only with DLXS middleware,
+
-
  and will provide simple access control assuming a pre-existing web authentication
+
-
  mechanism. Thoughts into the preliminary design of this system are welcome...and
+
-
  encouraged! Please [mailto:csnavely@umich.edu?subject=thoughts%20on%20dlxs%20auth%20%22lite%22  contact the author] of this document to share your ideas.</p>
+
-
<p> The following software or systems are required:
+
* provide off-campus users with authenticated access to locally-hosted resources
-
<ul>
+
* leverage an existing Kerberos authentication infrastructure in a web environment
-
  <li>[http://httpd.apache.org/ Apache 1.3.26] or higher with [http://www.modssl.org/ mod_ssl
+
* provide other institutions with IP address range-based access to locally-hosted resources
-
        2.8.10] or higher and mod_so, but not Apache 2.x</li>
+
-
  <li>[http://web.mit.edu/kerberos/www/ Kerberos V5] 1.2 or higher</li>
+
-
  <li><a href="http://www.openssl.org/">OpenSSL 0.9.6</a> or higher<br>
+
-
      </BR>
+
==Technical overview==
-
  </li>
+
-
  <li><a href="http://www.oracle.com/">Oracle 9i Server</a> or higher.</li>
+
-
</ul>
+
-
In addition, the following skills or staff will be required for installation
+
-
and/or maintenance:<br>
+
-
</BR>
+
-
<ul>
+
-
  <li>familiarity with the C programming language</li>
+
-
  <li>administrative access to the Apache server and Oracle Server installations</li>
+
The system is made up of three components:
-
  <li>familiarity with Oracle administration and with SQL syntax for inserting,
+
-
      deleting, and manipulating data in tables<br>
+
-
      </BR>
+
-
  </li>
+
-
</ul>
+
-
Note: it is OK, and in fact preferred, for an instance of Apache to run on the
+
-
same server with Oracle to provide only the user interface of the system. It
+
-
is <i>not</i> recommended that Oracle Server be installed alongside Apache on
+
-
servers that are intended for heavy web service use.
+
-
</P>
+
-
<p> Note: This system will establish an Oracle session for each Apache server
+
-
  process. If you expect the number of Apache web servers to be high, it is
+
-
  recommended that you configure Oracle to use shared servers to ensure scalability.</p>
+
-
<h1><a name="inst"></a>Installation</h1><ol>
+
# authentication and authorization database: Here is stored all information on user accounts and user groups, institution names and IP address ranges, collections or resources, and access permissions--which users and institutions may access which collections or resources. This must be an Oracle database.
-
<li><b>Unpack the distribution archive.</b> The system is distributed as a compressed
+
# Apache web server module: This modular extension to Apache acts as a gatekeeper to all of the material on the web server, consulting the database in real time. It uses the access control information in the database to grant access, deny access, or request authentication. In addition, it implements the user interface which accepts a username and password, or which guides new users through the process of setting their initial password.
-
  tar archive. Extract the contents of the archive into an area on your system
+
# Page templates: The Apache module uses these fully-customizable HTML templates to generate the pages in the user interface.
-
  where software is typically installed; e.g., <tt> /usr/local/dlps_auth</tt> .<br>
+
-
  </BR>
+
-
</li>
+
-
<li><b>Set up the Oracle tablespace. </b>The following instructions will create
+
-
  an Oracle user, tablespace, and tables to support the system. Ideally, you
+
-
  should have your Oracle administrator at least looking over your shoulder
+
-
  for this portion of the installation.</li>
+
-
<ol>
+
-
<li>Change to the directory where SQL scripts are supplied with the command (e.g.) <tt>cd
+
==Requirements==
-
      /usr/local/dlps_auth/sql</tt> .</li>
+
-
<li>Carefully edit the file <tt>create_tablespace.sql</tt> , substituting the
+
-
  correct local customizations for Oracle data file locations as needed.</li>
+
-
<li>Carefully edit the file <tt>create_tables.sql</tt> , substituting the correct
+
-
  system administrator email address for sysadmin@your.domain on line 133.<br>
+
-
  </BR>
+
-
 
+
-
</li>
+
-
<li>Start the SQL monitor with the command <tt>sqlplus system</tt> (you will
+
-
  be prompted for the Oracle system password).</li>
+
-
<li>Create the schema and tablespace with the command <tt> @create_tablespace</tt> .</li>
+
-
<li>Set a new password for the dlps_auth user, exit from the SQL monitor, and
+
-
  restart the SQL monitor with the command <tt> sqlplus dlps_auth</tt> (you
+
-
  will be prompted for the new dlps_auth password).</li>
+
-
 
+
-
<li>Create all required tables with the command<tt> @create_tables</tt> .</li>
+
-
<li><tt>C</tt>reate the unique identifier and timestamp triggers with the command <tt>@create_triggers</tt>.</li>
+
-
<li>Define the primary keys with the command <tt> @key</tt> .</li>
+
-
 
+
-
<li>Create the auxiliary indexes with the command <tt> @index</tt> .</li>
+
-
<li>Define the stored procedures with the command <tt> @dlps_auth</tt> .</li>
+
-
</ol>
+
-
<li><b>Modify the module source code.</b> Several behaviors and settings are
+
-
  still compiled into the module source (<tt>mod_dlps_auth.c</tt> ), and will
+
-
  require hand customization.</li>
+
-
 
+
-
<ol>
+
-
<li>Starting on line 345, the function change_passwd contains user interface
+
-
  logic that lets a user select one of two Kerberos realms, and is specific
+
-
  to the UM environment. This section will probably need modification based
+
-
  on your local authentication environment.</li>
+
-
<li>Starting on line 686, the confirmation email message that is sent when a
+
-
  user successfully changes his/her password will need modification as is appropriate
+
-
  to your environment.</li>
+
-
<li>On line 1437, the domain name associated with the cookie that is used for
+
-
  persistent authentication should be changed to your local domain.</li>
+
-
</ol>
+
-
<li><b>Compile and install the module.</b></li>
+
-
<ol>
+
-
<li>Carefully edit the file <tt>Makefile</tt>, substituting the installation
+
-
  paths of Kerberos, OpenSSL, and Oracle as appropriate.</li>
+
-
<li>Compile the module with the command <tt>make</tt> .</li>
+
-
 
+
-
<li>Install the module into your Apache installation with the command <tt>make
+
-
      install</tt>.</li>
+
-
</ol>
+
-
<li><b>Configure and activate the system.</b> The following instructions will
+
-
  modify your Apache configuration and immediately create some amount of load
+
-
  on your Oracle server. Ideally, you should have your Apache administrator
+
-
  at least looking over your shoulder for this portion of the installation.</li>
+
-
<ol>
+
-
<li>Carefully edit the configuration file (e.g.) <tt> /usr/local/dlps_auth/etc/dlps_auth.conf</tt> ,
+
-
  substituting the appropriate local values, as indicated below:</li>
+
-
<ol>
+
-
 
+
-
<li>Set <tt>DLPSAuthOracleHome</tt> to your Oracle installation home directory.</li>
+
-
<li>Set <tt>DLPSAuthOracleTNSName</tt> to the global TNS name of your Oracle
+
-
  server.</li>
+
-
<li>Set <tt>DLPSAuthOraclePassword</tt> to the password you assigned for the
+
-
  dlps_auth user in Step 2.6.</li>
+
-
<li>Set <tt>DLPSAuthEncryptionKey</tt> to 16 random characters.</li>
+
-
 
+
-
<li>Set <tt>DLPSAuthEnterPasswordServer</tt> to the server name you'll use to
+
-
  host the login page.</li>
+
-
<li>Set <tt>DLPSAuthCookieLifetime</tt> to the number of seconds you'd like authentication
+
-
  to persist, or 0 if you'd like authentication to expire when the user's browser
+
-
  is closed.</li>
+
-
<li>Set <tt>DLPSAuthChangePasswordServer</tt> to the server name you'll use to
+
-
  host the login page.</li>
+
-
<li>Set <tt>DLPSAuthPasswordResultsServer</tt> to the server name you'll use
+
-
  to host the login page.</li>
+
-
 
+
-
<li>Set <tt>DLPSAuthDefDestOnAuthenSuccess</tt> to a URL that the system should
+
-
  redirect users to after successful authentication if, for some reason, it
+
-
  is unable to determine the referring page.</li>
+
-
<li>Set <tt>DLPSAuthDelayOnAuthenSuccess</tt> to the number of seconds to display
+
-
  the page that informs the user that he/she authenticated successfully (before
+
-
  redirecting him/her back to the referring page).</li>
+
-
<li>Set <tt>DLPSAuthDocumentRoot</tt> to the directory containing the HTML templates,
+
-
  e.g. <tt>/usr/local/dlps_auth/html/templates</tt> .<br>
+
-
 
+
-
  </BR>
+
-
</li>
+
-
<li>Set <tt>DLPSAuthHelpContact</tt> to the email address that should receive
+
-
  replies to password change confirmation emails from users.</li>
+
-
<li>Set <tt>DLPSAuthSysAdminContact</tt> to the email address that should receive
+
-
  bounced delivery attempts to password confirmation emails</li>
+
-
</ol>
+
-
<li>Reference this configuration file in your Apache configuration file with
+
-
  the directive (e.g.) <tt>Include /usr/local/dlps_auth/etc/dlps_auth.conf</tt> .<br>
+
-
 
+
-
  </BR>
+
-
</li>
+
-
<li>Restart Apache with the command <tt>apachectl restart</tt> , and check the
+
-
  error log to ensure that the server restarted successfully. If it didn't,
+
-
  you can easily remove the system from your configuration by placing a <tt> #</tt> character
+
-
  in front of the <tt>Include</tt> directive above and restarting Apache.</li>
+
-
</ol></ol>If all went well, the system is now running and ready to accept access
+
-
controls!<br>
+
-
 
+
-
</BR>
+
-
<ol> <ol> <ol> </ol></ol></ol><h1><a name="acc"></a>Adding access controls</h1>
+
-
<p> In the database, an access control is made up of three parts: 1) a collection
+
-
  record, which is essentially one or more server names and directory paths;
+
-
  2) a user or institution record; and 3) an access record indicating the user
+
-
  or institution and the collection. In this way, collections, users, and institutions
+
-
  can be defined, and access permissions can be given in any combination.</p>
+
-
<p> The following sequence of example SQL commands will demonstrate the routine
+
-
  tasks associated with maintaining access controls in the database.</p>
+
-
<h4>Example: Creating a collection record</h4>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
-
  <tbody>
+
-
 
+
-
  <tr>
+
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
-
        insert into aa_coll (uniqueIdentifier,<br>
+
-
        </BR>
+
-
        commonName,<br>
+
-
        </BR>
+
-
        description,<br>
+
-
 
+
-
        </BR>
+
-
        dlpsClass, dlpsSource,<br>
+
-
        </BR>
+
-
        dlpsAuthenMethod, dlpsAuthzType,<br>
+
-
        </BR>
+
-
        dlpsPartlyPublic,<br>
+
-
        </BR>
+
-
 
+
-
        manager,<br>
+
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values ('jbt',<br>
+
-
 
+
-
        </BR>
+
-
        'Journal of Bobbles and Trinkets',<br>
+
-
        </BR>
+
-
        'An online resource focusing on the<br>
+
-
        </BR>
+
-
        study of buttons, plastic toys,<br>
+
-
        </BR>
+
-
 
+
-
        do-nothing machines, and the like',<br>
+
-
        </BR>
+
-
        'local', 'local',<br>
+
-
        </BR>
+
-
        'any', 'n',<br>
+
-
        </BR>
+
-
        'f',<br>
+
-
 
+
-
        </BR>
+
-
        0,<br>
+
-
        </BR>
+
-
        SYSDATE, 'root', 'f');</pre> </td>
+
-
      <td valign="top">Description of database columns:<br>
+
-
        </BR>
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
 
+
-
            <tbody>
+
-
            <tr>
+
-
              <td valign="top"><tt>uniqueIdentifier</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the (unique) collection identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>commonName</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the collection name<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>description</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">a textual description of the collection<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>dlpsClass</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the collection class (for use with DLXS middleware
+
-
                  classes)<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>dlpsSource</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the source of the material<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>dlpsAuthenMethod</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the authentication method to use: either 'ip'
+
-
                  (IP address range-based authentication, 'pw' (forced password
+
-
                  authentication), or 'any' (a combination of the two)<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>dlpsAuthzType</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the authorization type to use: either 'n' (normal)
+
-
                  or 'd' (delegated)<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsPartlyPublic</pre> </td>
+
-
              <td valign="top">a flag indicating whether the material is public:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            <tr>
+
-
              <td valign="top"><tt>manager</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the user group responsible for managing this
+
-
                  collection entry<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            <tr>
+
-
              <td valign="top"><tt>lastModifiedTime</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the date and time this record was last modified<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            <tr>
+
-
              <td valign="top"><tt>lastModifiedBy</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the username of the user who last modified this
+
-
                  record<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            <tr>
+
-
              <td valign="top"><tt>dlpsDeleted</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">a flag indicating whether this record is deleted:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            </tbody>
+
-
        </table></td>
+
-
  </tr>
+
-
  </tbody>
+
-
</table>
+
-
<h4>Example: Associating a server and directory with a collection</h4>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
-
  <tbody>
+
-
  <tr>
+
-
      <td valign="top"><pre><br>
+
-
 
+
-
        </BR>
+
-
        insert into aa_coll_obj (dlpsServer,<br>
+
-
        </BR>
+
-
        dlpsPath,<br>
+
-
        </BR>
+
-
        coll,<br>
+
-
        </BR>
+
-
 
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values ('www.your.domain',<br>
+
-
        </BR>
+
-
        '/usr/local/apache/htdocs/jbt%',<br>
+
-
 
+
-
        </BR>
+
-
        'jbt',<br>
+
-
        </BR>
+
-
        SYSDATE, 'root', 'f');<br>
+
-
        </BR>
+
-
        <br>
+
-
        </BR>
+
-
        </pre> </td>
+
-
 
+
-
      <td valign="top"> Description of database columns:<br>
+
-
        </BR>
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
            <tbody>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsServer</pre> </td>
+
-
              <td valign="top">the hostname of the web server<br>
+
-
 
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsPath</pre> </td>
+
-
              <td valign="top">the full file system path where the material
+
-
                  is stored; note the "%" wildcard at the end of the path, which
+
-
                  allows the access control to be applied to all contained files
+
-
                  and directories<br>
+
-
                  </BR>
+
-
 
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>coll</pre> </td>
+
-
              <td valign="top">the corresponding collection identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedTime</pre> </td>
+
-
              <td valign="top">the date and time this record was last modified<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedBy</pre> </td>
+
-
              <td valign="top">the username of the user who last modified this
+
-
                  record<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
 
+
-
              <td valign="top"><pre>dlpsDeleted<br>
+
-
                  </BR>
+
-
                  </pre> </td>
+
-
              <td valign="top">a flag indicating whether this record is deleted:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            </tbody>
+
-
        </table></td>
+
-
  </tr>
+
-
  </tbody>
+
-
</table>
+
-
<p> At this point, any attempt to access this resource, which is non-public and
+
-
  yet has no access permissions, should result in a prompt for authentication.</p>
+
-
<h4>Example: Creating an institution record</h4>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
-
  <tbody>
+
-
 
+
-
  <tr>
+
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
-
        insert into aa_inst (uniqueIdentifier,<br>
+
-
        </BR>
+
-
        organizationName, manager,<br>
+
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
 
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values (1000,<br>
+
-
        </BR>
+
-
        'University of Michigan', 0,<br>
+
-
        </BR>
+
-
 
+
-
        SYSDATE, 'root', 'f');</pre> </td>
+
-
      <td valign="top"> Description of database columns:<br>
+
-
        </BR>
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
            <tbody>
+
-
            <tr>
+
-
              <td valign="top"><tt>uniqueIdentifier</tt></td>
+
-
 
+
-
              <td valign="top">the (unique) institution identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>organizationName</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
              <td valign="top">the institution name<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>manager</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
              <td valign="top">the user group responsible for managing this
+
-
                  collection entry<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>lastModifiedTime</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
              <td valign="top">the date and time this record was last modified<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>lastModifiedBy</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
              <td valign="top">the username of the user who last modified this
+
-
                  record<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>dlpsDeleted</tt><br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
              <td valign="top">a flag indicating whether this record is deleted:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            </tbody>
+
-
        </table></td>
+
-
  </tr>
+
-
  </tbody>
+
-
 
+
-
</table>
+
-
<h4>Example: Associating an IP address range with an institution</h4>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
-
  <tbody>
+
-
  <tr>
+
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
-
        insert into aa_network (dlpsCIDRAddress,<br>
+
-
        </BR>
+
-
 
+
-
        dlpsAddressStart, dlpsAddressEnd,<br>
+
-
        </BR>
+
-
        dlpsAccessSwitch, inst,<br>
+
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
-
 
+
-
        </BR>
+
-
        values ('141.211.0.0/15',<br>
+
-
        </BR>
+
-
        2379415552,2379546623,<br>
+
-
        </BR>
+
-
        'allow', 1000,<br>
+
-
        </BR>
+
-
 
+
-
        SYSDATE, 'root', 'f');</pre> </td>
+
-
      <td valign="top"> Description of database columns:<br>
+
-
        </BR>
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
            <tbody>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsCIDRAddress</pre> </td>
+
-
 
+
-
              <td valign="top">the IP address range in CIDR format<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsAddressStart</pre> </td>
+
-
              <td valign="top">the numeric starting address of the range<br>
+
-
 
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsAddressEnd</pre> </td>
+
-
              <td valign="top">the numeric ending address of the range<br>
+
-
                  </BR>
+
-
 
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsAccessSwitch</pre> </td>
+
-
              <td valign="top">a flag indicating whether this address range
+
-
                  is to be allowed or denied: either 'allow' or 'deny'<br>
+
-
                  </BR>
+
-
              </td>
+
-
 
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>inst</pre> </td>
+
-
              <td valign="top">the corresponding institution identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
 
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedTime</pre> </td>
+
-
              <td valign="top">the date and time this record was last modified<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
 
+
-
              <td valign="top"><pre>lastModifiedBy</pre> </td>
+
-
              <td valign="top">the username of the user who last modified this
+
-
                  record<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsDeleted</pre> </td>
+
-
 
+
-
              <td valign="top">a flag indicating whether this record is deleted:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            </tbody>
+
-
        </table></td>
+
-
  </tr>
+
-
  </tbody>
+
-
 
+
-
</table>
+
-
<p>The system allows multiple IP address ranges to be associated with each institution.</p>
+
-
<h4>Example: Permitting an institution to a collection</h4>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
-
  <tbody>
+
-
  <tr>
+
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
-
        insert into aa_may_access (inst, coll,<br>
+
-
 
+
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values (1000, 'jbt',<br>
+
-
        </BR>
+
-
 
+
-
        SYSDATE, 'root', 'f');<br>
+
-
        </BR>
+
-
        </pre> </td>
+
-
      <td valign="top"> Description of database columns:<br>
+
-
        </BR>
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
            <tbody>
+
-
 
+
-
            <tr>
+
-
              <td valign="top"><pre>inst</pre> </td>
+
-
              <td valign="top">the corresponding institution identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
 
+
-
              <td valign="top"><pre>coll</pre> </td>
+
-
              <td valign="top">the corresponding collection identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedTime</pre> </td>
+
-
              <td valign="top">the date and time this record was last modified<br>
+
This is a robust system that supplies a complete campus authentication and authorization environment, and as such, it has heavy requirements that may be out of reach for some institutions or impractical for some purposes. DLXS acknowledges this, and will also be undertaking development of a "Lite" version of this system that requires nothing beyond the [../intro/sysreq.html standard DLXS system requirements]. This product is currently being shaped, but will probably be geared strictly toward interoperation only with DLXS middleware, and will provide simple access control assuming a pre-existing web authentication mechanism. Thoughts into the preliminary design of this system are welcome...and encouraged! Please [mailto:csnavely@umich.edu?subject=thoughts%20on%20dlxs%20auth%20%22lite%22  contact the author of this document] to share your ideas.
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedBy</pre> </td>
+
-
              <td valign="top">the username of the user who last modified this
+
-
                  record<br>
+
-
                  </BR>
+
The following software or systems are required:
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsDeleted</pre> </td>
+
-
              <td valign="top">a flag indicating whether this record is deleted:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
-
              </td>
+
* [http://httpd.apache.org/ Apache 1.3.26] or higher with [http://www.modssl.org/ mod_ssl 2.8.10] or higher and mod_so, but not Apache 2.x
-
            </tr>
+
* [http://web.mit.edu/kerberos/www/ Kerberos V5] 1.2 or higher
-
            </tbody>
+
* [http://www.openssl.org/ OpenSSL 0.9.6] or higher<br />
-
        </table></td>
+
* [http://www.oracle.com/ Oracle 9i Server] or higher.
-
  </tr>
+
-
  </tbody>
+
-
</table>
+
-
<p> At this point, the resource will be accessible from the UM campus, but any
+
-
  attempt to access it from elsewhere should result in a prompt for authentication.
+
-
  However, as no users currently exist, it will not be possible to authenticate.</p>
+
-
<h4>Example: Creating a user</h4>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
In addition, the following skills or staff will be required for installation and/or maintenance:<br />
-
  <tbody>
+
-
  <tr>
+
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
-
        insert inst aa_user (userid,<br>
+
-
        </BR>
+
-
        givenName, initials, surname,<br>
+
-
        </BR>
+
* familiarity with the C programming language
-
        rfc822Mailbox,<br>
+
* administrative access to the Apache server and Oracle Server installations
-
        </BR>
+
* familiarity with Oracle administration and with SQL syntax for inserting, deleting, and manipulating data in tables<br />
-
        dlpsKey, userPassword,<br>
+
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
Note: it is OK, and in fact preferred, for an instance of Apache to run on the same server with Oracle to provide only the user interface of the system. It is ''not'' recommended that Oracle Server be installed alongside Apache on servers that are intended for heavy web service use.
-
        </BR>
+
-
        values ('cufarley',<br>
+
-
        </BR>
+
-
        'Charles', 'U.', 'Farley',<br>
+
-
        </BR>
+
-
        'cufarley@your.domain',<br>
+
-
        </BR>
+
Note: This system will establish an Oracle session for each Apache server process. If you expect the number of Apache web servers to be high, it is recommended that you configure Oracle to use shared servers to ensure scalability.
-
        '123-45-6789', '!none',<br>
+
-
        </BR>
+
-
        SYSDATE, 'root', 'f');<br>
+
-
        </BR>
+
-
        </pre> </td>
+
-
      <td valign="top"> Description of database columns:<br>
+
-
        </BR>
+
==Installation==
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
            <tbody>
+
-
            <tr>
+
-
              <td valign="top"><pre>userid</pre> </td>
+
-
              <td valign="top">the (unique) user identifier<br>
+
-
                  </BR>
+
-
              </td>
+
# '''Unpack the distribution archive.''' The system is distributed as a compressed tar archive. Extract the contents of the archive into an area on your system where software is typically installed; e.g., <tt> /usr/local/dlps_auth</tt> .<br />
-
            </tr>
+
# '''Set up the Oracle tablespace. '''The following instructions will create an Oracle user, tablespace, and tables to support the system. Ideally, you should have your Oracle administrator at least looking over your shoulder for this portion of the installation.
-
            <tr>
+
## Change to the directory where SQL scripts are supplied with the command (e.g.) <tt>cd /usr/local/dlps_auth/sql</tt> .
-
              <td valign="top"><pre>givenName</pre> </td>
+
## Carefully edit the file <tt>create_tablespace.sql</tt> , substituting the correct local customizations for Oracle data file locations as needed.
-
              <td valign="top">the given (first) name<br>
+
## Carefully edit the file <tt>create_tables.sql</tt> , substituting the correct system administrator email address for sysadmin@your.domain on line 133.<br />
-
                  </BR>
+
## Start the SQL monitor with the command <tt>sqlplus system</tt> (you will be prompted for the Oracle system password).
-
              </td>
+
## Create the schema and tablespace with the command <tt> @create_tablespace</tt> .
 +
## Set a new password for the dlps_auth user, exit from the SQL monitor, and restart the SQL monitor with the command <tt> sqlplus dlps_auth</tt> (you will be prompted for the new dlps_auth password).
 +
## Create all required tables with the command<tt> @create_tables</tt> .
 +
## <tt>C</tt>reate the unique identifier and timestamp triggers with the command <tt>@create_triggers</tt>.
 +
## Define the primary keys with the command <tt> @key</tt> .
 +
## Create the auxiliary indexes with the command <tt> @index</tt> .
 +
## Define the stored procedures with the command <tt> @dlps_auth</tt> .
 +
# '''Modify the module source code.''' Several behaviors and settings are still compiled into the module source (<tt>mod_dlps_auth.c</tt> ), and will require hand customization.
 +
## Starting on line 345, the function change_passwd contains user interface logic that lets a user select one of two Kerberos realms, and is specific to the UM environment. This section will probably need modification based on your local authentication environment.
 +
## Starting on line 686, the confirmation email message that is sent when a user successfully changes his/her password will need modification as is appropriate to your environment.
 +
## On line 1437, the domain name associated with the cookie that is used for persistent authentication should be changed to your local domain.
 +
# '''Compile and install the module.'''
 +
## Carefully edit the file <tt>Makefile</tt>, substituting the installation paths of Kerberos, OpenSSL, and Oracle as appropriate.
 +
## Compile the module with the command <tt>make</tt> .
 +
## Install the module into your Apache installation with the command <tt>make install</tt>.
 +
# '''Configure and activate the system.''' The following instructions will modify your Apache configuration and immediately create some amount of load on your Oracle server. Ideally, you should have your Apache administrator at least looking over your shoulder for this portion of the installation.
 +
## Carefully edit the configuration file (e.g.) <tt> /usr/local/dlps_auth/etc/dlps_auth.conf</tt> , substituting the appropriate local values, as indicated below:
 +
### Set <tt>DLPSAuthOracleHome</tt> to your Oracle installation home directory.
 +
### Set <tt>DLPSAuthOracleTNSName</tt> to the global TNS name of your Oracle server.
 +
### Set <tt>DLPSAuthOraclePassword</tt> to the password you assigned for the dlps_auth user in Step 2.6.
 +
### Set <tt>DLPSAuthEncryptionKey</tt> to 16 random characters.
 +
### Set <tt>DLPSAuthEnterPasswordServer</tt> to the server name you'll use to host the login page.
 +
### Set <tt>DLPSAuthCookieLifetime</tt> to the number of seconds you'd like authentication to persist, or 0 if you'd like authentication to expire when the user's browser is closed.
 +
### Set <tt>DLPSAuthChangePasswordServer</tt> to the server name you'll use to host the login page.
 +
### Set <tt>DLPSAuthPasswordResultsServer</tt> to the server name you'll use to host the login page.
 +
### Set <tt>DLPSAuthDefDestOnAuthenSuccess</tt> to a URL that the system should redirect users to after successful authentication if, for some reason, it is unable to determine the referring page.
 +
### Set <tt>DLPSAuthDelayOnAuthenSuccess</tt> to the number of seconds to display the page that informs the user that he/she authenticated successfully (before redirecting him/her back to the referring page).
 +
### Set <tt>DLPSAuthDocumentRoot</tt> to the directory containing the HTML templates, e.g. <tt>/usr/local/dlps_auth/html/templates</tt> .<br />
 +
### Set <tt>DLPSAuthHelpContact</tt> to the email address that should receive replies to password change confirmation emails from users.
 +
### Set <tt>DLPSAuthSysAdminContact</tt> to the email address that should receive bounced delivery attempts to password confirmation emails
 +
## Reference this configuration file in your Apache configuration file with the directive (e.g.) <tt>Include /usr/local/dlps_auth/etc/dlps_auth.conf</tt> .<br />
 +
## Restart Apache with the command <tt>apachectl restart</tt> , and check the error log to ensure that the server restarted successfully. If it didn't, you can easily remove the system from your configuration by placing a <tt> #</tt> character in front of the <tt>Include</tt> directive above and restarting Apache.
-
            </tr>
+
If all went well, the system is now running and ready to accept access controls!<br />
-
            <tr>
+
-
              <td valign="top"><pre>initials</pre> </td>
+
-
              <td valign="top">the middle initial(s)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
==Adding access controls==
-
              <td valign="top"><pre>surname</pre> </td>
+
-
              <td valign="top">the surname<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>rfc822Mailbox</pre> </td>
+
In the database, an access control is made up of three parts: 1) a collection record, which is essentially one or more server names and directory paths; 2) a user or institution record; and 3) an access record indicating the user or institution and the collection. In this way, collections, users, and institutions can be defined, and access permissions can be given in any combination.
-
              <td valign="top">the email address<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsKey</pre> </td>
+
-
              <td valign="top">the "key" value which will permit the user to
+
The following sequence of example SQL commands will demonstrate the routine tasks associated with maintaining access controls in the database.
-
                  establish or change their password using the self-serve user
+
-
                  interface; this should be known only to the user<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>userPassword</pre> </td>
+
-
              <td valign="top">the encrypted password or Kerberos authentication
+
-
                  realm; this should be initially set to '!none', and will be
+
-
                  set by the user<br>
+
-
                  </BR>
+
==== Example: Creating a collection record ====
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedTime</pre> </td>
+
-
              <td valign="top">the date and time this record was last modified<br>
+
-
                  </BR>
+
-
              </td>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
            </tr>
+
| valign="top" |
-
            <tr>
+
<br />
-
              <td valign="top"><pre>lastModifiedBy</pre> </td>
+
-
              <td valign="top">the username of the user who last modified this
+
          insert into aa_coll (uniqueIdentifier,<br />
-
                  record<br>
+
-
                  </BR>
+
          commonName,<br />
-
              </td>
+
 +
          description,<br />
 +
 +
          dlpsClass, dlpsSource,<br />
 +
 +
          dlpsAuthenMethod, dlpsAuthzType,<br />
 +
 +
          dlpsPartlyPublic,<br />
 +
 +
          manager,<br />
 +
 +
          lastModifiedTime, lastModifiedBy,<br />
 +
 +
          dlpsDeleted)<br />
 +
 +
          values ('jbt',<br />
 +
 +
          'Journal of Bobbles and Trinkets',<br />
 +
 +
          'An online resource focusing on the<br />
 +
 +
          study of buttons, plastic toys,<br />
 +
 +
          do-nothing machines, and the like',<br />
 +
 +
          'local', 'local',<br />
 +
 +
          'any', 'n',<br />
 +
 +
          'f',<br />
 +
 +
          0,<br />
 +
 +
          SYSDATE, 'root', 'f');
 +
| valign="top" |
 +
Description of database columns:<br />
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" | <tt>uniqueIdentifier</tt><br />
 +
| valign="top" | the (unique) collection identifier<br />
 +
|-
 +
| valign="top" | <tt>commonName</tt><br />
 +
| valign="top" | the collection name<br />
 +
|-
 +
| valign="top" | <tt>description</tt><br />
 +
| valign="top" | a textual description of the collection<br />
 +
|-
 +
| valign="top" | <tt>dlpsClass</tt><br />
 +
| valign="top" | the collection class (for use with DLXS middleware classes)<br />
 +
|-
 +
| valign="top" | <tt>dlpsSource</tt><br />
 +
| valign="top" | the source of the material<br />
 +
|-
 +
| valign="top" | <tt>dlpsAuthenMethod</tt><br />
 +
| valign="top" | the authentication method to use: either 'ip' (IP address range-based authentication, 'pw' (forced password authentication), or 'any' (a combination of the two)<br />
 +
|-
 +
| valign="top" | <tt>dlpsAuthzType</tt><br />
 +
| valign="top" | the authorization type to use: either 'n' (normal) or 'd' (delegated)<br />
 +
|-
 +
| valign="top" |
 +
dlpsPartlyPublic
 +
| valign="top" | a flag indicating whether the material is public: either 't' (true) or 'f' (false)<br />
 +
|-
 +
| valign="top" | <tt>manager</tt><br />
 +
| valign="top" | the user group responsible for managing this collection entry<br />
 +
|-
 +
| valign="top" | <tt>lastModifiedTime</tt><br />
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" | <tt>lastModifiedBy</tt><br />
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" | <tt>dlpsDeleted</tt><br />
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)<br />
 +
|}
 +
|}
-
            </tr>
+
==== Example: Associating a server and directory with a collection ====
-
            <tr>
+
-
              <td valign="top"><pre>dlpsDeleted</pre> </td>
+
-
              <td valign="top">a flag indicating whether this record is deleted:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            </tbody>
+
{| ! width="75%" cellspacing="2" cellpadding="2"
-
        </table></td>
+
| valign="top" |
-
  </tr>
+
<br />
-
  </tbody>
+
-
</table>
+
          insert into aa_coll_obj (dlpsServer,<br />
-
<h4>Example: Associating a user with an institution</h4>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
          dlpsPath,<br />
-
  <tbody>
+
-
  <tr>
+
          coll,<br />
-
      <td valign="top"><pre><br>
+
 +
          lastModifiedTime, lastModifiedBy,<br />
 +
 +
          dlpsDeleted)<br />
 +
 +
          values ('www.your.domain',<br />
 +
 +
          '/usr/local/apache/htdocs/jbt%',<br />
 +
 +
          'jbt',<br />
 +
 +
          SYSDATE, 'root', 'f');<br />
 +
 +
          <br />
 +
 +
 +
| valign="top" |
 +
Description of database columns:<br />
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" |
 +
dlpsServer
 +
| valign="top" | the hostname of the web server<br />
 +
|-
 +
| valign="top" |
 +
dlpsPath
 +
| valign="top" | the full file system path where the material is stored; note the "%" wildcard at the end of the path, which allows the access control to be applied to all contained files and directories<br />
 +
|-
 +
| valign="top" |
 +
coll
 +
| valign="top" | the corresponding collection identifier<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedTime
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedBy
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" |
 +
dlpsDeleted<br />
 +
 +
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)<br />
 +
|}
 +
|}
-
        </BR>
+
At this point, any attempt to access this resource, which is non-public and yet has no access permissions, should result in a prompt for authentication.
-
        insert into aa_is_member_of_inst (userid, inst,<br>
+
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values ('cufarley', 1000,<br>
+
==== Example: Creating an institution record ====
-
        </BR>
+
-
        SYSDATE, 'root', 'f');<br>
+
-
        </BR>
+
-
        </pre> </td>
+
-
      <td valign="top"> Description of database columns:
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
            <tbody>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
            <tr>
+
| valign="top" |
-
              <td valign="top"><pre>userid</pre> </td>
+
<br />
-
              <td valign="top">the corresponding user identifier<br>
+
-
                  </BR>
+
          insert into aa_inst (uniqueIdentifier,<br />
-
              </td>
+
-
            </tr>
+
          organizationName, manager,<br />
 +
 +
          lastModifiedTime, lastModifiedBy,<br />
 +
 +
          dlpsDeleted)<br />
 +
 +
          values (1000,<br />
 +
 +
          'University of Michigan', 0,<br />
 +
 +
          SYSDATE, 'root', 'f');
 +
| valign="top" |
 +
Description of database columns:<br />
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" | <tt>uniqueIdentifier</tt>
 +
| valign="top" | the (unique) institution identifier<br />
 +
|-
 +
| valign="top" | <tt>organizationName</tt><br />
 +
| valign="top" | the institution name<br />
 +
|-
 +
| valign="top" | <tt>manager</tt><br />
 +
| valign="top" | the user group responsible for managing this collection entry<br />
 +
|-
 +
| valign="top" | <tt>lastModifiedTime</tt><br />
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" | <tt>lastModifiedBy</tt><br />
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" | <tt>dlpsDeleted</tt><br />
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)<br />
 +
|}
 +
|}
-
            <tr>
+
==== Example: Associating an IP address range with an institution ====
-
              <td valign="top"><pre>inst</pre> </td>
+
-
              <td valign="top">the corresponding institution identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedTime</pre> </td>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
              <td valign="top">the date and time this record was last modified<br>
+
| valign="top" |
-
                  </BR>
+
<br />
-
              </td>
+
-
            </tr>
+
          insert into aa_network (dlpsCIDRAddress,<br />
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedBy</pre> </td>
+
          dlpsAddressStart, dlpsAddressEnd,<br />
 +
 +
          dlpsAccessSwitch, inst,<br />
 +
 +
          lastModifiedTime, lastModifiedBy,<br />
 +
 +
          dlpsDeleted)<br />
 +
 +
          values ('141.211.0.0/15',<br />
 +
 +
          2379415552,2379546623,<br />
 +
 +
          'allow', 1000,<br />
 +
 +
          SYSDATE, 'root', 'f');
 +
| valign="top" |
 +
Description of database columns:<br />
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" |
 +
dlpsCIDRAddress
 +
| valign="top" | the IP address range in CIDR format<br />
 +
|-
 +
| valign="top" |
 +
dlpsAddressStart
 +
| valign="top" | the numeric starting address of the range<br />
 +
|-
 +
| valign="top" |
 +
dlpsAddressEnd
 +
| valign="top" | the numeric ending address of the range<br />
 +
|-
 +
| valign="top" |
 +
dlpsAccessSwitch
 +
| valign="top" | a flag indicating whether this address range is to be allowed or denied: either 'allow' or 'deny'<br />
 +
|-
 +
| valign="top" |
 +
inst
 +
| valign="top" | the corresponding institution identifier<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedTime
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedBy
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" |
 +
dlpsDeleted
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)<br />
 +
|}
 +
|}
-
              <td valign="top">the username of the user who last modified this
+
The system allows multiple IP address ranges to be associated with each institution.
-
                  record<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>dlpsDeleted</pre> </td>
+
-
              <td valign="top">a flag indicating whether this record is deleted:
+
-
                  either 't' (true) or 'f' (false)<br>
+
-
                  </BR>
+
==== Example: Permitting an institution to a collection ====
-
              </td>
+
-
            </tr>
+
-
            </tbody>
+
-
        </table></td>
+
-
  </tr>
+
-
  </tbody>
+
-
</table>
+
-
<p> At this point, after being prompted for authentication, the user may authenticate
+
-
  and will be given access to the resource.</p>
+
-
<h4>Example: Permitting a user to a collection</h4>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
<p>Access to collections may be given to individual users directly instead of
+
| valign="top" |
-
  via association with an institution. The following commands would modify the
+
<br />
-
  database to remove the association of the user with the institution, and explicitly
+
-
  permit the user to the collection. (Compare with <b>Permitting an institution
+
          insert into aa_may_access (inst, coll,<br />
-
  to a collection</b>, above.)</p>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
          lastModifiedTime, lastModifiedBy,<br />
-
  <tbody>
+
-
  <tr>
+
          dlpsDeleted)<br />
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
          values (1000, 'jbt',<br />
-
        delete from aa_is_member_of_inst<br>
+
 +
          SYSDATE, 'root', 'f');<br />
 +
 +
 +
| valign="top" |
 +
Description of database columns:<br />
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" |
 +
inst
 +
| valign="top" | the corresponding institution identifier<br />
 +
|-
 +
| valign="top" |
 +
coll
 +
| valign="top" | the corresponding collection identifier<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedTime
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedBy
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" |
 +
dlpsDeleted
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)<br />
 +
|}
 +
|}
-
        </BR>
+
At this point, the resource will be accessible from the UM campus, but any attempt to access it from elsewhere should result in a prompt for authentication. However, as no users currently exist, it will not be possible to authenticate.
-
        where userid = 'cufarley' and inst = 1000;<br>
+
-
        </BR>
+
-
        <br>
+
-
        </BR>
+
-
        insert into aa_may_access (userid, coll,<br>
+
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
==== Example: Creating a user ====
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values ('cufarley', 'jbt',<br>
+
-
        </BR>
+
-
        SYSDATE, 'root', 'f');</pre> </td>
+
-
  </tr>
+
-
  </tbody>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
</table>
+
| valign="top" |
-
<h4>Example: Creating a DLXS text class collection record</h4>
+
<br />
-
<p>Collections served by DLXS class middleware use a special mode of the system
+
-
  called "delegated authorization", which will be explained in more detail in
+
          insert inst aa_user (userid,<br />
-
  the next example. First, though, to trigger this mode, DLXS class collections
+
-
  must specify both their class (e.g. text or image) and the appropriate authorization
+
          givenName, initials, surname,<br />
-
  type flag, as shown below:</p>
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
          rfc822Mailbox,<br />
-
  <tbody>
+
-
  <tr>
+
          dlpsKey, userPassword,<br />
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
          lastModifiedTime, lastModifiedBy,<br />
-
        insert into aa_coll (uniqueIdentifier,<br>
+
 +
          dlpsDeleted)<br />
 +
 +
          values ('cufarley',<br />
 +
 +
          'Charles', 'U.', 'Farley',<br />
 +
 +
          'cufarley@your.domain',<br />
 +
 +
          '123-45-6789', '!none',<br />
 +
 +
          SYSDATE, 'root', 'f');<br />
 +
 +
 +
| valign="top" |
 +
Description of database columns:<br />
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" |
 +
userid
 +
| valign="top" | the (unique) user identifier<br />
 +
|-
 +
| valign="top" |
 +
givenName
 +
| valign="top" | the given (first) name<br />
 +
|-
 +
| valign="top" |
 +
initials
 +
| valign="top" | the middle initial(s)<br />
 +
|-
 +
| valign="top" |
 +
surname
 +
| valign="top" | the surname<br />
 +
|-
 +
| valign="top" |
 +
rfc822Mailbox
 +
| valign="top" | the email address<br />
 +
|-
 +
| valign="top" |
 +
dlpsKey
 +
| valign="top" | the "key" value which will permit the user to establish or change their password using the self-serve user interface; this should be known only to the user<br />
 +
|-
 +
| valign="top" |
 +
userPassword
 +
| valign="top" | the encrypted password or Kerberos authentication realm; this should be initially set to '!none', and will be set by the user<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedTime
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedBy
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" |
 +
dlpsDeleted
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)<br />
 +
|}
 +
|}
-
        </BR>
+
==== Example: Associating a user with an institution ====
-
        commonName,<br>
+
-
        </BR>
+
-
        description,<br>
+
-
        </BR>
+
-
        dlpsClass, dlpsSource,<br>
+
-
        </BR>
+
-
        dlpsAuthenMethod, dlpsAuthzType,<br>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
        </BR>
+
| valign="top" |
-
        dlpsPartlyPublic,<br>
+
<br />
-
        </BR>
+
-
        manager,<br>
+
          insert into aa_is_member_of_inst (userid, inst,<br />
-
        </BR>
+
-
        lastModifiedTime, lastModifiedBy,<br>
+
          lastModifiedTime, lastModifiedBy,<br />
 +
 +
          dlpsDeleted)<br />
 +
 +
          values ('cufarley', 1000,<br />
 +
 +
          SYSDATE, 'root', 'f');<br />
 +
 +
 +
| valign="top" |
 +
Description of database columns:
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" |
 +
userid
 +
| valign="top" | the corresponding user identifier<br />
 +
|-
 +
| valign="top" |
 +
inst
 +
| valign="top" | the corresponding institution identifier<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedTime
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedBy
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" |
 +
dlpsDeleted
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)<br />
 +
|}
 +
|}
-
        </BR>
+
At this point, after being prompted for authentication, the user may authenticate and will be given access to the resource.
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values ('jbt-text',<br>
+
-
        </BR>
+
-
        'Journal of Bobbles and Trinkets',<br>
+
-
        </BR>
+
-
        'An online resource focusing on the<br>
+
==== Example: Permitting a user to a collection ====
-
        </BR>
+
-
        study of buttons, plastic toys,<br>
+
-
        </BR>
+
-
        do-nothing machines, and the like',<br>
+
-
        </BR>
+
-
        'text', 'local',<br>
+
-
        </BR>
+
Access to collections may be given to individual users directly instead of via association with an institution. The following commands would modify the database to remove the association of the user with the institution, and explicitly permit the user to the collection. (Compare with '''Permitting an institution to a collection''', above.)
-
        'any', 'd',<br>
+
-
        </BR>
+
-
        'f',<br>
+
-
        </BR>
+
-
        0,<br>
+
-
        </BR>
+
-
        SYSDATE, 'root', 'f');</pre> </td>
+
{| width="75%" cellspacing="2" cellpadding="2"
-
      <td valign="top">Description of database columns, where different from <b>Creating
+
| valign="top" |
-
            a collection record.</b> above:<br>
+
<br />
-
        </BR>
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
          delete from aa_is_member_of_inst<br />
-
            <tbody>
+
-
            <tr>
+
          where userid = 'cufarley' and inst = 1000;<br />
 +
 +
          <br />
 +
 +
          insert into aa_may_access (userid, coll,<br />
 +
 +
          lastModifiedTime, lastModifiedBy,<br />
 +
 +
          dlpsDeleted)<br />
 +
 +
          values ('cufarley', 'jbt',<br />
 +
 +
          SYSDATE, 'root', 'f');
 +
|}
-
              <td valign="top"><tt>dlpsClass</tt><br>
+
==== Example: Creating a DLXS text class collection record ====
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the collection class (for use with DLXS middleware
+
-
                  classes)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><tt>dlpsAuthzType</tt><br>
+
Collections served by DLXS class middleware use a special mode of the system called "delegated authorization", which will be explained in more detail in the next example. First, though, to trigger this mode, DLXS class collections must specify both their class (e.g. text or image) and the appropriate authorization type flag, as shown below:
-
                  </BR>
+
-
              </td>
+
-
              <td valign="top">the authorization type to use: either 'n' (normal)
+
-
                  or 'd' (delegated)<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            </tbody>
+
-
        </table>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
        <br>
+
| valign="top" |
-
        </BR>
+
<br />
-
      </td>
+
-
  </tr>
+
          insert into aa_coll (uniqueIdentifier,<br />
-
  </tbody>
+
-
</table>
+
          commonName,<br />
-
<h4>Example: Permitting an institution to a DLXS text class collection</h4>
+
-
<p> When a permission is given to a collection that is set for delegated authorization,
+
          description,<br />
-
  as above, the system behaves in a completely different way. Instead of acting
+
-
  as a gatekeeper, the system instead collects all pertinent authorization information
+
          dlpsClass, dlpsSource,<br />
-
  and passes that information via environment variables to the DLXS middleware.
+
-
  The DLXS middleware will then use that information to decide which collections
+
          dlpsAuthenMethod, dlpsAuthzType,<br />
-
  to present to the user.</p>
+
 +
          dlpsPartlyPublic,<br />
 +
 +
          manager,<br />
 +
 +
          lastModifiedTime, lastModifiedBy,<br />
 +
 +
          dlpsDeleted)<br />
 +
 +
          values ('jbt-text',<br />
 +
 +
          'Journal of Bobbles and Trinkets',<br />
 +
 +
          'An online resource focusing on the<br />
 +
 +
          study of buttons, plastic toys,<br />
 +
 +
          do-nothing machines, and the like',<br />
 +
 +
          'text', 'local',<br />
 +
 +
          'any', 'd',<br />
 +
 +
          'f',<br />
 +
 +
          0,<br />
 +
 +
          SYSDATE, 'root', 'f');
 +
| valign="top" |
 +
Description of database columns, where different from '''Creating a collection record.''' above:<br />
 +
{| width="100%" cellspacing="2" cellpadding="2"
 +
| valign="top" | <tt>dlpsClass</tt><br />
 +
| valign="top" | the collection class (for use with DLXS middleware classes)<br />
 +
|-
 +
| valign="top" | <tt>dlpsAuthzType</tt><br />
 +
| valign="top" | the authorization type to use: either 'n' (normal) or 'd' (delegated)<br />
 +
|}<br />
 +
|}
-
<p>This mode is necessary because DLXS middleware supports searching across multiple
+
==== Example: Permitting an institution to a DLXS text class collection ====
-
  collections. Because any given user may have different access permissions
+
-
  based on institutional associations or explicit permissions, it is impossible
+
-
  to simply grant or deny access on a global basis. Instead, the DLXS middleware
+
-
  must be supplied with a customized list of authorized collections on a per-transaction
+
-
  basis in order to present the user with all of the material they are permitted
+
-
  to access, and none of the material for which they are not. The authorization
+
-
  type is referred to as "delegated" because the system is "delegating" the
+
-
  authorization decision to the DLXS middleware.</p>
+
-
<p>For a description of the information that is passed from the system to the
+
-
  DLXS middleware and how it is used, see <a href="../auth/index.html">DLXS
+
-
  Authentication and Authorization</a>.</p>
+
-
<p>As you can see below, the command required to add the permission is the same
+
-
  regardless of the authorization type:
+
-
<table cellpadding="2" cellspacing="2" border="0" width="75%">
+
-
  <tbody>
+
-
  <tr>
+
-
      <td valign="top"><pre><br>
+
-
        </BR>
+
-
        insert into aa_may_access (inst, coll,<br>
+
-
        </BR>
+
When a permission is given to a collection that is set for delegated authorization, as above, the system behaves in a completely different way. Instead of acting as a gatekeeper, the system instead collects all pertinent authorization information and passes that information via environment variables to the DLXS middleware. The DLXS middleware will then use that information to decide which collections to present to the user.
-
        lastModifiedTime, lastModifiedBy,<br>
+
-
        </BR>
+
-
        dlpsDeleted)<br>
+
-
        </BR>
+
-
        values (1000, 'jbt-text',<br>
+
-
        </BR>
+
-
        SYSDATE, 'root', 'f');</pre> <br>
+
This mode is necessary because DLXS middleware supports searching across multiple collections. Because any given user may have different access permissions based on institutional associations or explicit permissions, it is impossible to simply grant or deny access on a global basis. Instead, the DLXS middleware must be supplied with a customized list of authorized collections on a per-transaction basis in order to present the user with all of the material they are permitted to access, and none of the material for which they are not. The authorization type is referred to as "delegated" because the system is "delegating" the authorization decision to the DLXS middleware.
-
        </BR>
+
-
      </td>
+
-
      <td valign="top"> Description of database columns:<br>
+
-
        </BR>
+
-
        <table cellpadding="2" cellspacing="2" border="0" width="100%">
+
-
            <tbody>
+
-
            <tr>
+
For a description of the information that is passed from the system to the DLXS middleware and how it is used, see [../auth/index.html DLXS Authentication and Authorization].
-
              <td valign="top"><pre>inst</pre> </td>
+
-
              <td valign="top">the corresponding institution identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>coll</pre> </td>
+
As you can see below, the command required to add the permission is the same regardless of the authorization type:
-
              <td valign="top">the corresponding collection identifier<br>
+
-
                  </BR>
+
-
              </td>
+
-
            </tr>
+
-
            <tr>
+
-
              <td valign="top"><pre>lastModifiedTime</pre> </td>
+
-
              <td valign="top">the date and time this record was last modified<br>
+
{| !width="75%" cellspacing="2" cellpadding="2"
-
                  </BR>
+
| valign="top" |
-
              </td>
+
<br />
-
            </tr>
+
-
            <tr>
+
          insert into aa_may_access (inst, coll,<br />
-
              <td valign="top"><pre>lastModifiedBy</pre> </td>
+
-
              <td valign="top">the username of the user who last modified this
+
          lastModifiedTime, lastModifiedBy,<br />
-
                  record<br>
+
 +
          dlpsDeleted)<br />
 +
 +
          values (1000, 'jbt-text',<br />
 +
 +
          SYSDATE, 'root', 'f');
-
                  </BR>
+
<br />
-
              </td>
+
| valign="top" |
-
            </tr>
+
Description of database columns:<br />
-
            <tr>
+
{| width="100%" cellspacing="2" cellpadding="2"
-
              <td valign="top"><pre>dlpsDeleted</pre> </td>
+
| valign="top" |
-
              <td valign="top">a flag indicating whether this record is deleted:
+
inst
-
                  either 't' (true) or 'f' (false)</td>
+
| valign="top" | the corresponding institution identifier<br />
-
            </tr>
+
|-
 +
| valign="top" |
 +
coll
 +
| valign="top" | the corresponding collection identifier<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedTime
 +
| valign="top" | the date and time this record was last modified<br />
 +
|-
 +
| valign="top" |
 +
lastModifiedBy
 +
| valign="top" | the username of the user who last modified this record<br />
 +
|-
 +
| valign="top" |
 +
dlpsDeleted
 +
| valign="top" | a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)
 +
|}<br />
 +
|}
-
            </tbody>
+
= Appendix: Features of the UM Digital Library Services installation =
-
        </table>
+
-
        <br>
+
-
        </BR>
+
-
      </td>
+
-
  </tr>
+
-
  </tbody>
+
-
</table>
+
-
</P>
+
-
<h1><a name="local"></a>Appendix: Features of the UM Digital Library Services
+
-
installation</h1>
+
-
<p>Our local installation of this system includes the following:
+
Our local installation of this system includes the following:
-
<ul>
+
-
  <li><b>Oracle configuration.</b> Two Oracle 9i servers are installed in two
+
-
      different, and distant, parts of campus. These servers use replication
+
-
      features of Oracle to stay in near-real-time synchronization; if a change
+
-
      is made on one server, that change will be replicated to the other server
+
-
      in less than one minute. All Oracle client software has been configured
+
-
      with connect-time and session failover capabilities so that the Oracle
+
-
      server which is physically closest is preferred under normal circumstances,
+
-
      but the other will be chosen in the event of a failure. One server is Sun
+
-
      hardware running Solaris, and the other is Intel hardware running Linux.</li>
+
-
  <li><b>Apache web server configuration.</b> Apache, equipped with mod_ssl
+
-
      and the DLXS authentication and authorization system, is running alongside
+
-
      Oracle on each server. Each Apache installation is configured with a copy
+
-
      of a server certificate for the name "login.umdl.umich.edu" and has identical
+
-
      appearance in all respects.</li>
+
-
  <li><b>Load balancing and failover.</b> A DNS-based system has been put in
+
-
      place to dynamically direct users' browsers to the Apache server that is
+
-
      physically closest under normal circumstances, to the least loaded server
+
-
      under heavy usage conditions, or to the only available server in the event
+
-
      of a failure. A user accessing the server "login.umdl.umich.edu" may transparently
+
-
      hit either server.<br>
+
-
      </BR>
+
* '''Oracle configuration.''' Two Oracle 9i servers are installed in two different, and distant, parts of campus. These servers use replication features of Oracle to stay in near-real-time synchronization; if a change is made on one server, that change will be replicated to the other server in less than one minute. All Oracle client software has been configured with connect-time and session failover capabilities so that the Oracle server which is physically closest is preferred under normal circumstances, but the other will be chosen in the event of a failure. One server is Sun hardware running Solaris, and the other is Intel hardware running Linux.
-
  </li>
+
* '''Apache web server configuration.''' Apache, equipped with mod_ssl and the DLXS authentication and authorization system, is running alongside Oracle on each server. Each Apache installation is configured with a copy of a server certificate for the name "login.umdl.umich.edu" and has identical appearance in all respects.
-
  <li><b>Locally-hosted text and image resources.</b> Servers that are dedicated
+
* '''Load balancing and failover.''' A DNS-based system has been put in place to dynamically direct users' browsers to the Apache server that is physically closest under normal circumstances, to the least loaded server under heavy usage conditions, or to the only available server in the event of a failure. A user accessing the server "login.umdl.umich.edu" may transparently hit either server.<br />
-
      to serving text and image content are equipped with the DLXS authentication
+
* '''Locally-hosted text and image resources.''' Servers that are dedicated to serving text and image content are equipped with the DLXS authentication and authorization system if they host any non-public content. The database is maintained with records which restrict access to these materials as needed. At the time of this writing, there are approximately 500 active institutions records in the database for institutions with subscriptions to resources hosted by DLS.
-
      and authorization system if they host any non-public content. The database
+
* '''Library web server.''' The library's main web server also has the system installed, and restricted access to materials such as course reserves and staff-only areas of the website is provided through the system via IP address range or password authentication, as appropriate.
-
      is maintained with records which restrict access to these materials as
+
* '''Library catalog.''' The Web-accessible interface to the library's catalog has been enhanced to honor the authentication cookie used by the system, and uses that to enable saved record sets, patron self-service functions, and other functions requiring authentication.
-
      needed. At the time of this writing, there are approximately 500 active
+
* '''Library proxy server.''' The library's proxy server, EZProxy, was enhanced with a small custom script to honor the authentication cookie used by the system to initialize a proxy session. UM affiliates who have authenticated for other reasons are automatically granted a proxy session.<br />
-
      institutions records in the database for institutions with subscriptions
+
-
      to resources hosted by DLS.</li>
+
-
  <li><b>Library web server.</b> The library's main web server also has the
+
-
      system installed, and restricted access to materials such as course reserves
+
-
      and staff-only areas of the website is provided through the system via
+
-
      IP address range or password authentication, as appropriate.</li>
+
-
  <li><b>Library catalog.</b> The Web-accessible interface to the library's
+
-
      catalog has been enhanced to honor the authentication cookie used by the
+
-
      system, and uses that to enable saved record sets, patron self-service
+
-
      functions, and other functions requiring authentication.</li>
+
-
  <li><b>Library proxy server.</b> The library's proxy server, EZProxy, was
+
[[#top|Top]]
-
      enhanced with a small custom script to honor the authentication cookie
+
-
      used by the system to initialize a proxy session. UM affiliates who have
+
-
      authenticated for other reasons are automatically granted a proxy session.<br>
+
-
      </BR>
+
-
  </li>
+
-
</ul>
+
-
</P>
+

Current revision

Main Page > Ancillary Resources > DLXS Authentication and Authorization System

Contents

[edit] Functional overview

The DLXS Authentication and Authorization system is a complete access control system designed primarily for use in digital library environments. It can interoperate with core DLXS middleware to control access to collections, or it can be used as a standalone access control system in a general web environment.

The system has the following general capabilities:

  • user authentication, using either a self-contained encrypted password or existing Kerberos authentication server(s)
  • user self-service: each user can set or reset his/her password, and will receive automated confirmation email after doing so
  • institutional authentication using IP address ranges
  • centralized management of all user, institution, and access information in an Oracle database

Designed to function with a heterogenous mix of resources, both public and restricted, this system could be useful if you are looking to do any of the following:

  • provide off-campus users with authenticated access to locally-hosted resources
  • leverage an existing Kerberos authentication infrastructure in a web environment
  • provide other institutions with IP address range-based access to locally-hosted resources

[edit] Technical overview

The system is made up of three components:

  1. authentication and authorization database: Here is stored all information on user accounts and user groups, institution names and IP address ranges, collections or resources, and access permissions--which users and institutions may access which collections or resources. This must be an Oracle database.
  2. Apache web server module: This modular extension to Apache acts as a gatekeeper to all of the material on the web server, consulting the database in real time. It uses the access control information in the database to grant access, deny access, or request authentication. In addition, it implements the user interface which accepts a username and password, or which guides new users through the process of setting their initial password.
  3. Page templates: The Apache module uses these fully-customizable HTML templates to generate the pages in the user interface.

[edit] Requirements

This is a robust system that supplies a complete campus authentication and authorization environment, and as such, it has heavy requirements that may be out of reach for some institutions or impractical for some purposes. DLXS acknowledges this, and will also be undertaking development of a "Lite" version of this system that requires nothing beyond the [../intro/sysreq.html standard DLXS system requirements]. This product is currently being shaped, but will probably be geared strictly toward interoperation only with DLXS middleware, and will provide simple access control assuming a pre-existing web authentication mechanism. Thoughts into the preliminary design of this system are welcome...and encouraged! Please contact the author of this document to share your ideas.

The following software or systems are required:

In addition, the following skills or staff will be required for installation and/or maintenance:

  • familiarity with the C programming language
  • administrative access to the Apache server and Oracle Server installations
  • familiarity with Oracle administration and with SQL syntax for inserting, deleting, and manipulating data in tables

Note: it is OK, and in fact preferred, for an instance of Apache to run on the same server with Oracle to provide only the user interface of the system. It is not recommended that Oracle Server be installed alongside Apache on servers that are intended for heavy web service use.

Note: This system will establish an Oracle session for each Apache server process. If you expect the number of Apache web servers to be high, it is recommended that you configure Oracle to use shared servers to ensure scalability.

[edit] Installation

  1. Unpack the distribution archive. The system is distributed as a compressed tar archive. Extract the contents of the archive into an area on your system where software is typically installed; e.g., /usr/local/dlps_auth .
  2. Set up the Oracle tablespace. The following instructions will create an Oracle user, tablespace, and tables to support the system. Ideally, you should have your Oracle administrator at least looking over your shoulder for this portion of the installation.
    1. Change to the directory where SQL scripts are supplied with the command (e.g.) cd /usr/local/dlps_auth/sql .
    2. Carefully edit the file create_tablespace.sql , substituting the correct local customizations for Oracle data file locations as needed.
    3. Carefully edit the file create_tables.sql , substituting the correct system administrator email address for sysadmin@your.domain on line 133.
    4. Start the SQL monitor with the command sqlplus system (you will be prompted for the Oracle system password).
    5. Create the schema and tablespace with the command @create_tablespace .
    6. Set a new password for the dlps_auth user, exit from the SQL monitor, and restart the SQL monitor with the command sqlplus dlps_auth (you will be prompted for the new dlps_auth password).
    7. Create all required tables with the command @create_tables .
    8. Create the unique identifier and timestamp triggers with the command @create_triggers.
    9. Define the primary keys with the command @key .
    10. Create the auxiliary indexes with the command @index .
    11. Define the stored procedures with the command @dlps_auth .
  3. Modify the module source code. Several behaviors and settings are still compiled into the module source (mod_dlps_auth.c ), and will require hand customization.
    1. Starting on line 345, the function change_passwd contains user interface logic that lets a user select one of two Kerberos realms, and is specific to the UM environment. This section will probably need modification based on your local authentication environment.
    2. Starting on line 686, the confirmation email message that is sent when a user successfully changes his/her password will need modification as is appropriate to your environment.
    3. On line 1437, the domain name associated with the cookie that is used for persistent authentication should be changed to your local domain.
  4. Compile and install the module.
    1. Carefully edit the file Makefile, substituting the installation paths of Kerberos, OpenSSL, and Oracle as appropriate.
    2. Compile the module with the command make .
    3. Install the module into your Apache installation with the command make install.
  5. Configure and activate the system. The following instructions will modify your Apache configuration and immediately create some amount of load on your Oracle server. Ideally, you should have your Apache administrator at least looking over your shoulder for this portion of the installation.
    1. Carefully edit the configuration file (e.g.) /usr/local/dlps_auth/etc/dlps_auth.conf , substituting the appropriate local values, as indicated below:
      1. Set DLPSAuthOracleHome to your Oracle installation home directory.
      2. Set DLPSAuthOracleTNSName to the global TNS name of your Oracle server.
      3. Set DLPSAuthOraclePassword to the password you assigned for the dlps_auth user in Step 2.6.
      4. Set DLPSAuthEncryptionKey to 16 random characters.
      5. Set DLPSAuthEnterPasswordServer to the server name you'll use to host the login page.
      6. Set DLPSAuthCookieLifetime to the number of seconds you'd like authentication to persist, or 0 if you'd like authentication to expire when the user's browser is closed.
      7. Set DLPSAuthChangePasswordServer to the server name you'll use to host the login page.
      8. Set DLPSAuthPasswordResultsServer to the server name you'll use to host the login page.
      9. Set DLPSAuthDefDestOnAuthenSuccess to a URL that the system should redirect users to after successful authentication if, for some reason, it is unable to determine the referring page.
      10. Set DLPSAuthDelayOnAuthenSuccess to the number of seconds to display the page that informs the user that he/she authenticated successfully (before redirecting him/her back to the referring page).
      11. Set DLPSAuthDocumentRoot to the directory containing the HTML templates, e.g. /usr/local/dlps_auth/html/templates .
      12. Set DLPSAuthHelpContact to the email address that should receive replies to password change confirmation emails from users.
      13. Set DLPSAuthSysAdminContact to the email address that should receive bounced delivery attempts to password confirmation emails
    2. Reference this configuration file in your Apache configuration file with the directive (e.g.) Include /usr/local/dlps_auth/etc/dlps_auth.conf .
    3. Restart Apache with the command apachectl restart , and check the error log to ensure that the server restarted successfully. If it didn't, you can easily remove the system from your configuration by placing a # character in front of the Include directive above and restarting Apache.

If all went well, the system is now running and ready to accept access controls!

[edit] Adding access controls

In the database, an access control is made up of three parts: 1) a collection record, which is essentially one or more server names and directory paths; 2) a user or institution record; and 3) an access record indicating the user or institution and the collection. In this way, collections, users, and institutions can be defined, and access permissions can be given in any combination.

The following sequence of example SQL commands will demonstrate the routine tasks associated with maintaining access controls in the database.

[edit] Example: Creating a collection record 




         insert into aa_coll (uniqueIdentifier,


         commonName,


         description,


         dlpsClass, dlpsSource,


         dlpsAuthenMethod, dlpsAuthzType,


         dlpsPartlyPublic,


         manager,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values ('jbt',


         'Journal of Bobbles and Trinkets',


         'An online resource focusing on the


         study of buttons, plastic toys,


         do-nothing machines, and the like',


         'local', 'local',


         'any', 'n',


         'f',


         0,


         SYSDATE, 'root', 'f');

Description of database columns:

uniqueIdentifier
 the (unique) collection identifier
commonName
 the collection name
description
 a textual description of the collection
dlpsClass
 the collection class (for use with DLXS middleware classes)
dlpsSource
 the source of the material
dlpsAuthenMethod
 the authentication method to use: either 'ip' (IP address range-based authentication, 'pw' (forced password authentication), or 'any' (a combination of the two)
dlpsAuthzType
 the authorization type to use: either 'n' (normal) or 'd' (delegated)
dlpsPartlyPublic
a flag indicating whether the material is public: either 't' (true) or 'f' (false)
manager
 the user group responsible for managing this collection entry
lastModifiedTime
 the date and time this record was last modified
lastModifiedBy
 the username of the user who last modified this record
dlpsDeleted
 a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

[edit] Example: Associating a server and directory with a collection 




         insert into aa_coll_obj (dlpsServer,


         dlpsPath,


         coll,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values ('www.your.domain',


         '/usr/local/apache/htdocs/jbt%',


         'jbt',


         SYSDATE, 'root', 'f');

Description of database columns:

dlpsServer
the hostname of the web server
dlpsPath
the full file system path where the material is stored; note the "%" wildcard at the end of the path, which allows the access control to be applied to all contained files and directories
coll
the corresponding collection identifier
lastModifiedTime
the date and time this record was last modified
lastModifiedBy
the username of the user who last modified this record
dlpsDeleted
a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

At this point, any attempt to access this resource, which is non-public and yet has no access permissions, should result in a prompt for authentication.

[edit] Example: Creating an institution record 




         insert into aa_inst (uniqueIdentifier,


         organizationName, manager,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values (1000,


         'University of Michigan', 0,


         SYSDATE, 'root', 'f');

Description of database columns:

uniqueIdentifier the (unique) institution identifier
organizationName
 the institution name
manager
 the user group responsible for managing this collection entry
lastModifiedTime
 the date and time this record was last modified
lastModifiedBy
 the username of the user who last modified this record
dlpsDeleted
 a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

[edit] Example: Associating an IP address range with an institution 




         insert into aa_network (dlpsCIDRAddress,


         dlpsAddressStart, dlpsAddressEnd,


         dlpsAccessSwitch, inst,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values ('141.211.0.0/15',


         2379415552,2379546623,


         'allow', 1000,


         SYSDATE, 'root', 'f');

Description of database columns:

dlpsCIDRAddress
the IP address range in CIDR format
dlpsAddressStart
the numeric starting address of the range
dlpsAddressEnd
the numeric ending address of the range
dlpsAccessSwitch
a flag indicating whether this address range is to be allowed or denied: either 'allow' or 'deny'
inst
the corresponding institution identifier
lastModifiedTime
the date and time this record was last modified
lastModifiedBy
the username of the user who last modified this record
dlpsDeleted
a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

The system allows multiple IP address ranges to be associated with each institution.

[edit] Example: Permitting an institution to a collection 




         insert into aa_may_access (inst, coll,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values (1000, 'jbt',


         SYSDATE, 'root', 'f');

Description of database columns:

inst
the corresponding institution identifier
coll
the corresponding collection identifier
lastModifiedTime
the date and time this record was last modified
lastModifiedBy
the username of the user who last modified this record
dlpsDeleted
a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

At this point, the resource will be accessible from the UM campus, but any attempt to access it from elsewhere should result in a prompt for authentication. However, as no users currently exist, it will not be possible to authenticate.

[edit] Example: Creating a user 




         insert inst aa_user (userid,


         givenName, initials, surname,


         rfc822Mailbox,


         dlpsKey, userPassword,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values ('cufarley',


         'Charles', 'U.', 'Farley',


         'cufarley@your.domain',


         '123-45-6789', '!none',


         SYSDATE, 'root', 'f');

Description of database columns:

userid
the (unique) user identifier
givenName
the given (first) name
initials
the middle initial(s)
surname
the surname
rfc822Mailbox
the email address
dlpsKey
the "key" value which will permit the user to establish or change their password using the self-serve user interface; this should be known only to the user
userPassword
the encrypted password or Kerberos authentication realm; this should be initially set to '!none', and will be set by the user
lastModifiedTime
the date and time this record was last modified
lastModifiedBy
the username of the user who last modified this record
dlpsDeleted
a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

[edit] Example: Associating a user with an institution 




         insert into aa_is_member_of_inst (userid, inst,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values ('cufarley', 1000,


         SYSDATE, 'root', 'f');

Description of database columns: 

userid
the corresponding user identifier
inst
the corresponding institution identifier
lastModifiedTime
the date and time this record was last modified
lastModifiedBy
the username of the user who last modified this record
dlpsDeleted
a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

At this point, after being prompted for authentication, the user may authenticate and will be given access to the resource.

[edit] Example: Permitting a user to a collection

Access to collections may be given to individual users directly instead of via association with an institution. The following commands would modify the database to remove the association of the user with the institution, and explicitly permit the user to the collection. (Compare with Permitting an institution to a collection, above.) 




         delete from aa_is_member_of_inst


         where userid = 'cufarley' and inst = 1000;


         


         insert into aa_may_access (userid, coll,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values ('cufarley', 'jbt',


         SYSDATE, 'root', 'f');

[edit] Example: Creating a DLXS text class collection record

Collections served by DLXS class middleware use a special mode of the system called "delegated authorization", which will be explained in more detail in the next example. First, though, to trigger this mode, DLXS class collections must specify both their class (e.g. text or image) and the appropriate authorization type flag, as shown below: 




         insert into aa_coll (uniqueIdentifier,


         commonName,


         description,


         dlpsClass, dlpsSource,


         dlpsAuthenMethod, dlpsAuthzType,


         dlpsPartlyPublic,


         manager,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values ('jbt-text',


         'Journal of Bobbles and Trinkets',


         'An online resource focusing on the


         study of buttons, plastic toys,


         do-nothing machines, and the like',


         'text', 'local',


         'any', 'd',


         'f',


         0,


         SYSDATE, 'root', 'f');

Description of database columns, where different from Creating a collection record. above:

dlpsClass
 the collection class (for use with DLXS middleware classes)
dlpsAuthzType
 the authorization type to use: either 'n' (normal) or 'd' (delegated)

[edit] Example: Permitting an institution to a DLXS text class collection

When a permission is given to a collection that is set for delegated authorization, as above, the system behaves in a completely different way. Instead of acting as a gatekeeper, the system instead collects all pertinent authorization information and passes that information via environment variables to the DLXS middleware. The DLXS middleware will then use that information to decide which collections to present to the user.

This mode is necessary because DLXS middleware supports searching across multiple collections. Because any given user may have different access permissions based on institutional associations or explicit permissions, it is impossible to simply grant or deny access on a global basis. Instead, the DLXS middleware must be supplied with a customized list of authorized collections on a per-transaction basis in order to present the user with all of the material they are permitted to access, and none of the material for which they are not. The authorization type is referred to as "delegated" because the system is "delegating" the authorization decision to the DLXS middleware.

For a description of the information that is passed from the system to the DLXS middleware and how it is used, see [../auth/index.html DLXS Authentication and Authorization].

As you can see below, the command required to add the permission is the same regardless of the authorization type: 




         insert into aa_may_access (inst, coll,


         lastModifiedTime, lastModifiedBy,


         dlpsDeleted)


         values (1000, 'jbt-text',


         SYSDATE, 'root', 'f');


Description of database columns:

inst
the corresponding institution identifier
coll
the corresponding collection identifier
lastModifiedTime
the date and time this record was last modified
lastModifiedBy
the username of the user who last modified this record
dlpsDeleted
a flag indicating whether this record is deleted: either 't' (true) or 'f' (false)

[edit] Appendix: Features of the UM Digital Library Services installation

Our local installation of this system includes the following:

  • Oracle configuration. Two Oracle 9i servers are installed in two different, and distant, parts of campus. These servers use replication features of Oracle to stay in near-real-time synchronization; if a change is made on one server, that change will be replicated to the other server in less than one minute. All Oracle client software has been configured with connect-time and session failover capabilities so that the Oracle server which is physically closest is preferred under normal circumstances, but the other will be chosen in the event of a failure. One server is Sun hardware running Solaris, and the other is Intel hardware running Linux.
  • Apache web server configuration. Apache, equipped with mod_ssl and the DLXS authentication and authorization system, is running alongside Oracle on each server. Each Apache installation is configured with a copy of a server certificate for the name "login.umdl.umich.edu" and has identical appearance in all respects.
  • Load balancing and failover. A DNS-based system has been put in place to dynamically direct users' browsers to the Apache server that is physically closest under normal circumstances, to the least loaded server under heavy usage conditions, or to the only available server in the event of a failure. A user accessing the server "login.umdl.umich.edu" may transparently hit either server.
  • Locally-hosted text and image resources. Servers that are dedicated to serving text and image content are equipped with the DLXS authentication and authorization system if they host any non-public content. The database is maintained with records which restrict access to these materials as needed. At the time of this writing, there are approximately 500 active institutions records in the database for institutions with subscriptions to resources hosted by DLS.
  • Library web server. The library's main web server also has the system installed, and restricted access to materials such as course reserves and staff-only areas of the website is provided through the system via IP address range or password authentication, as appropriate.
  • Library catalog. The Web-accessible interface to the library's catalog has been enhanced to honor the authentication cookie used by the system, and uses that to enable saved record sets, patron self-service functions, and other functions requiring authentication.
  • Library proxy server. The library's proxy server, EZProxy, was enhanced with a small custom script to honor the authentication cookie used by the system to initialize a proxy session. UM affiliates who have authenticated for other reasons are automatically granted a proxy session.

Top

Retrieved from "http://webservices.itcs.umich.edu/mediawiki/dlxs15/index.php/DLXS_Authentication_and_Authorization_System"
Personal tools