Authentication and Authorization
From DLXS Documentation
Revision as of 09:54, 22 July 2007
Contents |
Overview
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
a colon-delimited list of collection identifiers that the current user is explicitly authorized to access; i.e., authorized collections
PUBLIC_COLL
a colon-delimited list of collection identifiers that the current user may access without explicit authorization; i.e., public collections
and the variable that contains the username of the current user (for middleware such as the Collection Manager that requires you to log in) is:
REMOTE_USER
the username of the current user (if the user has logged in)
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.
Setting the List(s) of Accessible Collections
Using Static Settings
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.
Using a Custom (Dynamic) Authorization System
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.
Setting Up Authentication For Use With DLXS
Using Basic Authentication
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. Using a Custom Authentication System
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.
Authentication and Authorization (AUTHNZ) Extension Module
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.
If you decide to use a local authentication system, set your configuration as follows.
Looking at, for example DLXSROOT/web/t/text/home.xsl, observe that the href for the login link comes from the <ReauthLink> XML element. You can see this as XML by viewing your home page with "debug=xml" added to your URL. Set the global variable called $gAuthenticationEnabled in DLXSROOT/lib/LibGlobals.pm to q{1} (use the curly brace syntax).
In DLXSROOT/lib/AuthNZ.cfg, supply the values to your local authentication URLs in the AUTHNZ_libum section. <ReauthLink> XML will now be populated with those URL hrefs and you'll have a login link.
Note that once the user clicks on the login link they are in your local authentication system, not DLXS. It is up to your local authentication system to set the REMOTE_USER and AUTHZD_COLL and PUBLIC_COLL environment variables upon successful authentication and then redirect back to DLXS. This is the way DLXS interfaces to an authentication system.
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:
- Recognize one of several possible appropriate authentication and authorization modules
- Load that module dynamically
- Determine whether a requested resource is authorized by that module
- Create side-effects in the AUTHZD_COLL and PUBLIC_COLL and REMOTE_USER environment variables and store information in the session object (dso) to record this authorization
- Provide services supporting the creation of login and logout URLs
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.
- HandleAuthNandAuthZ
- BuildLoginOptionsPageURL
- HandleSpecificLoginUrlPI
- BuildSpecificLoginURL
- HandleGeneralLoginUrlPI
- GetGeneralLoginUrl
- GetCollidLoginURL
