DLXS Authentication and Authorization System
From DLXS Documentation
| Line 349: | Line 349: | ||
</table> | </table> | ||
| - | + | ===Example: Associating a server and directory with a collection=== | |
| - | <table | + | |
| + | <table border=1> | ||
<tr> | <tr> | ||
<td valign="top"> | <td valign="top"> | ||
| - | |||
| - | |||
<tt>insert into aa_coll_obj (dlpsServer, | <tt>insert into aa_coll_obj (dlpsServer, | ||
| Line 415: | Line 414: | ||
</td> | </td> | ||
</tr> | </tr> | ||
| - | |||
</table> | </table> | ||
Revision as of 15:56, 31 August 2007
Main Page > Ancillary Resources > DLXS Authentication and Authorization System
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
Technical overview
The system is made up of three components:
- 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.
- 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.
- Page templates: The Apache module uses these fully-customizable HTML templates to generate the pages in the user interface.
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:
- 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
- Kerberos V5 1.2 or higher
- OpenSSL 0.9.6 or higher
- Oracle 9i Server or higher.
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.
Installation
</li>
- Change to the directory where SQL scripts are supplied with the command (e.g.) cd /usr/local/dlps_auth/sql .
- Carefully edit the file create_tablespace.sql , substituting the correct local customizations for Oracle data file locations as needed.
- Carefully edit the file create_tables.sql , substituting the correct
system administrator email address for sysadmin@your.domain on line 133.
- Start the SQL monitor with the command sqlplus system (you will be prompted for the Oracle system password).
- Create the schema and tablespace with the command @create_tablespace .
- 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).
- Create all required tables with the command @create_tables .
- Create the unique identifier and timestamp triggers with the command @create_triggers.
- Define the primary keys with the command @key .
- Create the auxiliary indexes with the command @index .
- Define the stored procedures with the command @dlps_auth .
- 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.
- Carefully edit the file Makefile, substituting the installation paths of Kerberos, OpenSSL, and Oracle as appropriate.
- Compile the module with the command make .
- Install the module into your Apache installation with the command make install.
- Carefully edit the configuration file (e.g.) /usr/local/dlps_auth/etc/dlps_auth.conf , substituting the appropriate local values, as indicated below:
- Set DLPSAuthOracleHome to your Oracle installation home directory.
- Set DLPSAuthOracleTNSName to the global TNS name of your Oracle server.
- Set DLPSAuthOraclePassword to the password you assigned for the dlps_auth user in Step 2.6.
- Set DLPSAuthEncryptionKey to 16 random characters.
- Set DLPSAuthEnterPasswordServer to the server name you'll use to host the login page.
- 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.
- Set DLPSAuthChangePasswordServer to the server name you'll use to host the login page.
- Set DLPSAuthPasswordResultsServer to the server name you'll use to host the login page.
- 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.
- 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).
- Set DLPSAuthDocumentRoot to the directory containing the HTML templates,
e.g. /usr/local/dlps_auth/html/templates .
- Set DLPSAuthHelpContact to the email address that should receive replies to password change confirmation emails from users.
- Set DLPSAuthSysAdminContact 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.) Include /usr/local/dlps_auth/etc/dlps_auth.conf .
- 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.
controls!
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.
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:
|
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:
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. Example: Creating an institution record
Example: Associating an IP address range with an institution
The system allows multiple IP address ranges to be associated with each institution. Example: Permitting an institution to a collection
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. Example: Creating a user
Example: Associating a user with an institution
At this point, after being prompted for authentication, the user may authenticate and will be given access to the resource. Example: Permitting a user to a collectionAccess 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.)
Example: Creating a DLXS text class collection recordCollections 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:
Example: Permitting an institution to a DLXS text class collectionWhen 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 <a href="../auth/index.html">DLXS Authentication and Authorization</a>. As you can see below, the command required to add the permission is the same regardless of the authorization type:
Appendix: Features of the UM Digital Library Services InstallationOur local installation of this system includes the following:
|
