July 3, 2008

U of MN Central Auth Mod_Perl2 Module

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 11:19 PM