NAME

Lemonldap::NG::Handler - Perl extension for building a Lemonldap compatible handler

SYNOPSIS

Create your own package:

  package My::Package;
  use Lemonldap::NG::Handler;

  our @ISA = qw(Lemonldap::NG::Handler);

  __PACKAGE__->init ({locationRules => { 'default' => '$ou =~ /brh/'},
         globalStorage        => 'Apache::Session::MySQL',
         globalStorageOptions => {
               DataSource       => 'dbi:mysql:database=dbname;host=127.0.0.1',
               UserName         => 'db_user',
               Password         => 'db_password',
               TableName        => 'sessions',
               LockDataSource   => 'dbi:mysql:database=dbname;host=127.0.0.1',
               LockUserName     => 'db_user',
               LockPassword     => 'db_password',
           },
         localStorage         => 'Cache::DBFile',
         localStorageOptions  => {},
         portal               => 'https://portal/',
       });

More complete example

  package My::Package;
  use Lemonldap::NG::Handler;

  our @ISA = qw(Lemonldap::NG::Handler);

  __PACKAGE__->init ( { locationRules => {
             '^/pj/.*$'       => q($qualif="opj"),
             '^/rh/.*$'       => q($ou=~/brh/),
             '^/rh_or_opj.*$' => q($qualif="opj or $ou=~/brh/),
             default => 'accept', # means that all authenticated users are greanted
           },
           globalStorage        => 'Apache::Session::MySQL',
           globalStorageOptions => {
               DataSource       => 'dbi:mysql:database=dbname;host=127.0.0.1',
               UserName         => 'db_user',
               Password         => 'db_password',
               TableName        => 'sessions',
               LockDataSource   => 'dbi:mysql:database=dbname;host=127.0.0.1',
               LockUserName     => 'db_user',
               LockPassword     => 'db_password',
           },
           localStorage         => 'Cache::DBFile',
           localStorageOptions  => {},
           cookieName           => 'lemon',
           portal               => 'https://portal/',
           whatToTrace          => '$uid',
           exportedHeaders      => {
               'User-Auth'      => '$uid',
               'Unit'           => '$ou',
           https                => 1,
         }
       );

Call your package in <apache-directory>/conf/httpd.conf

  PerlRequire MyFile
  # TOTAL PROTECTION
  PerlInitHandler My::Package
  # OR SELECTED AREA
  <Location /protected-area>
    PerlInitHandler My::Package
  </Location>

DESCRIPTION

Lemonldap is a simple Web-SSO based on Apache::Session modules. It simplifies the build of a protected area with a few changes in the application (they just have to read some headers for accounting).

It manages both authentication and authorization and provides headers for accounting. So you can have a full AAA protection for your web space. There are two ways to build a cross domain authentication:

• Cross domain authentication itself (Lemonldap::Portal::Cda) (not yet implemented in Lemonldap::NG)

• "Liberty Alliance" (see Lemonldap::NG::ServiceProvider and Lemonldap::NG::IdentityProvider)

This library provides a simple agent (Apache handler) to protect a web area. It can be extended with other Lemonldap::NG::Handler::* modules to add various functionalities. For example :

• Lemonldap::NG::Handler::SharedConfig to be able to change handler configuration without restarting Apache

• Lemonldap::NG::Handler::Proxy to replace Apache mod_proxy if you have some problems (for example, managing redirections,...)

INITIALISATION PARAMETERS

This section presents the init method parameters.

locationRules (required)

Reference to a hash that contains "url-regexp => perl-expression" entries to manage authorizations.

• "url-regexp" can be a perl regexp or the keyword 'default' which corresponds to the default police (accept by default).

• "perl-expression" can be a perl condition or the keyword "accept" or the keyword "deny". All the variables announced by $<name of the variable> are replaced by the values resulting from the global session store.

globalStorage & globalStorageOptions (required)

Name and parameters of the Apache::Session::* module used by the portal to store user's datas. See Lemonldap::NG::Portal(3) for more explanations.

localStorage & localStorageOptions

Name and parameters of the optional but recommanded Cache::* module used to share user's datas between Apache processes. There is no need to set expires options since Lemonldap::NG::Handler call the Cache::*::purge method itself.

cookieName (default: lemon)

Name of the cookie used by the Lemonldap infrastructure.

portal (required)

Url of the portal used to authenticate users.

whatToTrace (default: uid)

Stored user variable to use in Apache logs.

exportedHeaders

Reference to a hash that contains "Name => value" entries. Those headers are calculated for each user by replacing the variables announced by "$" by their values resulting from the global session store.

https (default: 1)

Indicates if the protected server is protected by SSL. It is used to build redirections, so you have to set it to avoid bad redirections after authentication.

EXPORT

None by default. You can import the following tags for inheritance:

• :variables : all global variables

• :localStorage : variables used to manage local storage

• :import : import function inherited from Exporter and related variables

AUTHENTICATION-AUTHORIZATION-ACCOUNTING

This section presents Lemonldap characteristics from the point-of-vue of AAA.

Authentication

If a user isn't authenticated and attemps to connect to an area protected by a Lemonldap compatible handler, he is redirected to the portal. The portal authenticates user with a ldap bind by default, but you can also use another authentication sheme like using x509 user certificates (see Lemonldap::NG::Portal::AuthSSL for more).

Lemonldap use session cookies generated by Apache::Session so as secure as a 128-bit random cookie. You may use the cookie_secure options of Lemonldap::NG::Portal to avoid session hijacking.

You have to manage life of sessions by yourself since Lemonldap knows nothing about the Apache::Session module you've choose, but it's very easy using a simple cron script because Lemonldap::NG::Portal stores the start time in the _utime field.

Authorization

Authorization is controled only by handlers because the portal knows nothing about the way the user will choose. Lemonldap::NG::Portal is designed to help you to store all the user datas you wants to use to manage authorization.

When initializing an handler, you have to describe what you want to protect and who can connect to. This is done by the locationRules parameters of init method. It is a reference to a hash who contains entries where:

• keys are regular expression who are compiled by init using qr() or the keyword default who points to the default police.

• values are conditional expressions or the keyword accept or the keyword deny:

  • Conditional expressions are converted into subroutines. You can use the variables stored in the global store by calling them $<varname>.

    Exemple:

      '^/rh/.*$' => '$ou =~ /brh/'

  • Keyword deny denies any access while keyword accept allows all authenticated users.

    Exemple:

      'default'  => 'accept'

Accounting

Logging portal access

Lemonldap::NG::Portal doesn't log anything by default, but it's easy to overload log method for normal portal access or using error method to know what was wrong if process method has failed.

Logging application access

Because an handler knows nothing about the protected application, it can't do more than logging URL. As Apache does this fine, Lemonldap::NG::Handler gives it the name to used in logs. The whatToTrace parameters indicates which variable Apache has to use ($uid by default).

The real accounting has to be done by the application itself which knows the result of SQL transaction for example.

Lemonldap can export http headers either using a proxy or protecting directly the application. By default, the User-Auth field is used but you can change it using the exportedHeaders parameters of the init method. It is a reference to a hash where:

• keys are the names of the choosen headers

• values are perl expressions where you can use user datas stored in the global store by calling them $<varname>.

SEE ALSO

• Lemonldap::NG::Portal(3), Lemonldap::NG::Handler::Proxy(3)

• http://lemonldap.sourceforge.net/, http://projectliberty.org/

AUTHOR

Xavier Guimard, <x.guimard@free.fr>

COPYRIGHT AND LICENSE

Copyright (C) 2004, 2005 by Eric German & Xavier Guimard

Lemonldap was originaly written by Eric german who decided to publish him in 2003 under the terms of the GNU General Public License version 2.

• This library is free software; you can redistribute it and/or modify it under same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

• The primary copyright holder is Eric German.

• Portions are copyrighted under the GNU General Public License, Version 2

• Portions are copyrighted by Doug MacEachern and Lincoln Stein.

cpanm Lemonldap::NG::Handler

perl -MCPAN -e shell
install Lemonldap::NG::Handler