The system uses three variables in the web server (CGI) environment for authentication and authorization operations.
The variables which determine the collections the current user may access are
AUTHZD_COLL
PUBLIC_COLL
REMOTE_USER
To set up authentication and authorization in DLXS, mechanisms must be put in place to set the values of these variables according to your requirements. The following sections contain several examples of different methods to do this.
Important note: these lists must begin and end with a colon, and be colon-delimited.
Probably the simplest way to set the list of accessible collections is to statically set the AUTHZD_COLL
and/or PUBLIC_COLL
environment variables in the web server configuration. The advantage of this approach is that it is easy and fast; the disadvantage is that it is not very flexible: every user accessing the DLXS server will have the same access permissions. This approach works particularly well for a server which hosts only public collections, since hosting non-public collections generally entails allowing access to some users and not to others. For more information on setting static environment variables with the Apache web server, consult the documentation for the SetEnv
configuration directive at the Apache server home page.
The DLXS installation process creates a partial Apache configuration file that uses static settings as an example for you to work from. For more information about this example file, see the Apache config sample files documentation.
If you require different users to have different lists of permitted resources, then you will need to put a mechanism in place to dynamically set the values of AUTHZD_COLL
and/or PUBLIC_COLL
based on the IP address of the user's workstation, domain name, or some other method of authentication. Depending on your requirements, this may be simple enough to be handled in the web server configuration, or it may be complex enough to require an external system. At DLPS, the environment variables above are dynamically set for use by the DLXS system by an Apache module that queries an Oracle database (for more information on this system, see DLXS Authentication and Authorization System documentation), and plans are in place for a light-weight (Perl-based) system for a future release.
For sites with simple authentication requirements (e.g., if you just need to control several users' access to the Collection Manager), we recommend using standard HTTP Basic Authentication. Basic Authentication will ask users to enter a username and password for access to the directories you specify; after a user successfully authenticates, the environment variable REMOTE_USER will be set to the user's username, and then can be used by the DLXS system. For more information on configuring Basic Authentication with the Apache web server, consult the documentation at the Apache server home page.
The DLXS installation process creates a partial Apache configuration file that uses Basic Authentication as an example for you to work from. For more information about this example file, see the Apache config sample files documentation.
Any authentication mechanism that sets the REMOTE_USER
environment variable (which, by the way, is conventional for all properly-written web authentication systems) will work with DLXS. There are myriad available systems, varying mainly in the specific database or file method used to store usernames and passwords. For more information on authentication modules available for the Apache web server, see the Apache Module Registry.
DLXS implements access to the AUTHZD_COLL and PUBLIC_COLL environment variables described above via a perl base class called AuthNZ defined by lib/AuthNZ.pm. In addition to access to these variables (which constitute the default communication with the AUTHNZ system) AuthNZ can be subclassed to interface to other AUTHNZ systems such as Athens or Shiboleth. AuthNZ.pm defines an object-oriented class that implements methods to:
The AuthNZ class instantiation as an object (anzo) encapsulates and records the results of the authentication and authorization process, This object is attached to the session object (dso) for later reference.
The public interface to this module consists of the following routines.