I've written a mod_perl2 module: UMN::CAH::Client::MP2 to work with UMN::CAH::Client::Store to provide a client implementation of the University of Minnesota Central Authentication Hub.
Currently ::MP2 is on version 0.0.3 and ::Store is on version 0.0.5. Both of these should still be considered ALPHA software, use it at your own risk. :)
You can find the latest version of ::Store here and the latest version of ::MP2 here.
Please feel free to send me your comments, questions or bug reports. Note that I did not implement a test suite with ::MP2 since I haven't figured out how to do it yet.
Below is the documentation (from the embedded POD).
NAME
UMN::CAH::Client::MP2 - A mod_perl2 client implementation of the U of M
single sign-on authentication.
VERSION
This document describes UMN::CAH::Client::MP2 version 0.0.3
SYNOPSIS
Recommended: using a persistent object:
<perl>
use UMN::CAH::Client::MP2;
$Global::UMN::CAH::auth_object
= UMN::CAH::Client::MP2
->new(
allow_impersonation_by => [ 'cayfo001', ],
acl_file => '/home/apache2/default_acl_file',
);
</Perl>
<Directory /home/apache2/htdocs/restricted/>
AuthType Basic
PerlAuthenHandler $Global::UMN::CAH::auth_object->handler
Require valid-user
PerlAuthzHandler $Global::UMN::CAH::auth_object->handler
</Directory>
Alternative: using a new default object for each request:
<Location /restricted_access>
AuthType Basic
PerlAuthenHandler UMN::CAH::Client::MP2
Require valid-user
</Location>
DESCRIPTION
This is a mod_perl2 module to allow user authentication on the
University of Minnesota's Central Authentication Hub (CAH, AKA
"Cookieauth") single sign-on system. For more information on the CAH
system and other implemenations please visit
http://www1.umn.edu/is/cookieauth/.
This module handles the mod_perl front-end to the authentication and
authorization and relies on UMN::CAH::Client::Store to handle the
back-end -- that is, the details of verifying client cookies against the
U of M's servers and caching the responses.
This module should be considered alpha software. It was developed on
Debian and Ubuntu Linux and has only been tested under the Apache2
prefork engine. I would welcome contributions and comments to fix bugs,
make the code more portable, and any other general improvements.
INTERFACE
new
$object = UMN::CAH::Client::MP2->new( %config_options )
Class method to create a new MP2 object. The object holds a link to the
store and cache, so you should ideally call this in a Perl section of
the apache config file. This same object can then be referenced without
needing to create a new object again later.
Each object is configured at creation. If different parts of your
website need different configurations you can create multiple objects as
needed.
You can just use "UMN::CAH::Client::MP2" as an authentication handler as
illustrated in the synopsis, but this will incur the object creation
costs for each request and will only allow default configuration. Since
there is no default acl_file, this method cannot be used as an
authorization handler.
The new method accepts named arguments to configure the object
* acl_file
Full path to file to use for authorization (only relevant if called
in the PerlAuthzHandler). See below for the configuration
information. Default: undef
* allow_any_ip
Array of IP addresses. Requests from these clients will not be
checked for IP address consistency with the CAH cookie. Default: []
* allow_impersonation_by
Array of x500 ID's for clients who will be allowed to impersonate
other clients on this website. See below for impersonation details.
Default: []
* https_port
Port on which this webserver is running https. Any requests handled
by the authentication object which are not under https will be
redirected to the https port. Default: 443
* auth_server
The IP address or DNS name of the CAH server. Default: x500.umn.edu
* auth_port
The port on which to contact the CAH server. Default: 87
* auth_modulename
The X500 module to use for cookie authentication. Default: WEBCOOKIE
* login_url
The URL to which clients are directed to login to the U. Default:
https://www.umn.edu/login
* min_level
Minimum acceptable authentication level. Default: 30
* timeout_len
Authentication timeout time in seconds. This is measured in time
since the authentication cookie was originally created. This is not
necessarily the same time as when the client first hit this website.
Default: 10800 (three hours)
* rolling_timeout_len
Authentication timeout time in seconds since last activity on this
authentication cache. Setting this to zero deactivates this feature.
For example is set to 300, the authentication will be timed out if
the user is not active on this website at least once every five
minutes. Note that there no way to tell if they have been active on
other U of M websites so this feature has limited usefulness.
Default: 0 (inactive)
* share_file
Filename to provide to Cache::FastMmap as a cache file. Default:
/tmp/UMN_CAH_Client_Store_Cache
* enable_stats
Passed through to Cache::FastMmap. Default: undef
* expire_time
Passed through to Cache::FastMmap. Default: undef
* cache_size
Passed through to Cache::FastMmap. Default: undef
* page_size
Passed through to Cache::FastMmap. Default: undef
* num_pages
Passed through to Cache::FastMmap. Default: undef
* unlink_on_exit
Passed through to Cache::FastMmap. Default: undef
handler
$object->handler
The mod_perl entry point.
DIAGNOSTICS
TODO
CONFIGURATION AND ENVIRONMENT
ACL file
The ACL file provides a very simple authorization mechanism. The file
should be a sequence of lines where each line consists of one of two
directives: "allow" or "deny", followed by white space and then either
an x500 ID or the symbol "*". The ACL file is read from top to bottom
and processing stops at the first line to match the current client's ID.
The * will match any ID, so processing will never continue beyond a line
with a * ID. If the matching line's directive is allow access is
granted, otherwise it is denied. If processing reaches the end of the
file without finding a match, access is denied by default. Blank lines
are ignored as is anything on a line following the comment character: #.
The ACL file is only consulted if UMN::CAH::Client::MP2 is called in the
authorization phase (as a PerlAuthzHandler).
Impersonation
You can allow certain clients to impersonate others on a protected
website. If the ID of the authenticated user matches one listed in the
"allow_impersonation_by" option then they can choose to set the ID
passed on to Apache and other applications to another string.
Impersonation is done with a URL query in the form "impersonate=xxxxx".
If the current authenticated user has impersonation permissions and the
impersonate query is found in the current request then the effective ID
associated with this authentication cookie is set to the specified
string (xxxxx) and is used instead of the real ID to set Apache's user
variable.
A query of "impersonate=" (with an empty field after the = ) will reset
the effective ID to that of the real user.
The effect of this impersonation is limited to the area using the same
authentication cache file. It has no effect on any other websites.
Note that the authorization phase of UMN::CAH::Client::MP2 looks at the
effective ID rather than the real ID and so will be affected by
impersonation like any other script running under Apache.
DEPENDENCIES
Test::More
version
Carp
version
UMN::CAH::Client::Store
Apache2::RequestRec
Apache2::RequestIO
Apache2::Const
Apache2::URI
Apache2::Log
Apache2::Connection
APR::Request
APR::URI
ModPerl::Util
Apache2::ModSSL
INCOMPATIBILITIES
None reported.
BUGS AND LIMITATIONS
Please report any bugs or feature requests to the author.
AUTHOR
Steven Cayford "cayfo001@umn.edu"
LICENCE AND COPYRIGHT
Copyright (c) 2008, Steven Cayford "<cayfo001@umn.edu>". All rights
reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
Posted by cayfo001 at July 3, 2008 11:19 PM