|
|
|
|
@ -1,218 +1,21 @@ |
|
|
|
|
Lemonldap-NG |
|
|
|
|
LemonLDAP::NG |
|
|
|
|
==================== |
|
|
|
|
|
|
|
|
|
Lemonldap::NG is a modular Web-SSO based on Apache::Session modules. It |
|
|
|
|
simplifies the build of a protected area with a few changes in the application. |
|
|
|
|
LemonLDAP::NG is a modular Web-SSO based on Apache::Session modules. |
|
|
|
|
This is the handler part of it. You can find documentation here: |
|
|
|
|
* for administrators: http://lemonldap-ng.org/ |
|
|
|
|
* for developers: see embedded perldoc |
|
|
|
|
|
|
|
|
|
It manages both authentication and authorization and provides headers for |
|
|
|
|
accounting. So you can have a full AAA protection for your web space as |
|
|
|
|
described below. |
|
|
|
|
LemonLDAP::NG is a free software; you can redistribute it and/or modify |
|
|
|
|
it under the terms of the GNU General Public License as published by |
|
|
|
|
the Free Software Foundation; either version 2, or (at your option) |
|
|
|
|
any later version. |
|
|
|
|
|
|
|
|
|
1 - Installation |
|
|
|
|
2 - Authentication, Authorization and Accounting mechanisms |
|
|
|
|
2.1 - Authentication |
|
|
|
|
2.2 - Authorization |
|
|
|
|
2.3 - Accounting |
|
|
|
|
3 - Session storage system |
|
|
|
|
4 - Logout system |
|
|
|
|
5 - Author |
|
|
|
|
6 - Copyright and license |
|
|
|
|
This program is distributed in the hope that it will be useful, |
|
|
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of |
|
|
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
|
|
|
|
GNU General Public License for more details. |
|
|
|
|
|
|
|
|
|
1 - INSTALLATION |
|
|
|
|
================ |
|
|
|
|
You should have received a copy of the GNU General Public License |
|
|
|
|
along with this program. If not, see L<http://www.gnu.org/licenses/>. |
|
|
|
|
|
|
|
|
|
Lemonldap::NG is a different project than Lemonldap and contains all you need |
|
|
|
|
to use and administer it. So softwares, like Lemonldap webmin module, may not |
|
|
|
|
work with Lemonldap::NG. |
|
|
|
|
|
|
|
|
|
The Apache module part (Lemonldap::NG::Handler) works both with Apache 1.3.x |
|
|
|
|
and 2.x ie mod_perl 1 and 2 (but not with mod_perl 1.99). Portal and Manager |
|
|
|
|
act as CGI, so they can work everywhere. |
|
|
|
|
|
|
|
|
|
See INSTALL file in the whole source tree of Lemonldap::NG for a complete |
|
|
|
|
installation documentation. |
|
|
|
|
|
|
|
|
|
To install this module type the following: |
|
|
|
|
|
|
|
|
|
perl Makefile.PL |
|
|
|
|
make |
|
|
|
|
make test |
|
|
|
|
make install |
|
|
|
|
|
|
|
|
|
2 - AUTHENTICATION, AUTHORIZATION AND ACCOUNTING MECHANISMS |
|
|
|
|
=========================================================== |
|
|
|
|
|
|
|
|
|
Warning: Lemonldap::NG configuration has to be edited using the manager unless |
|
|
|
|
you know exactly what you are doing. The parameters discussed here are all in |
|
|
|
|
the configuration tree. |
|
|
|
|
|
|
|
|
|
2.1 - Authentication |
|
|
|
|
|
|
|
|
|
If a user isn't authenticated and attemps to connect to an area protected by a |
|
|
|
|
Lemonldap::NG compatible handler, he is redirected to a 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(3) for more). |
|
|
|
|
|
|
|
|
|
Lemonldap::NG use session cookies generated by Apache::Session so as secure as a |
|
|
|
|
128-bit random cookie. You may use the securedCookie options to avoid session |
|
|
|
|
hijacking. |
|
|
|
|
|
|
|
|
|
You have to manage life of sessions by yourself since Lemonldap::NG knows |
|
|
|
|
nothing about the L<Apache::Session> module you've choosed, but it's very easy |
|
|
|
|
using a simple cron script because Lemonldap::NG::Portal stores the start |
|
|
|
|
time in the _utime field. |
|
|
|
|
By default, a session stay 10 minutes in the local storage, so in the worth |
|
|
|
|
case, a user is authorized 10 minutes after he lost his rights. |
|
|
|
|
|
|
|
|
|
2.2 - Authorization |
|
|
|
|
|
|
|
|
|
Authorization is controled only by handlers because the portal knows nothing |
|
|
|
|
about the way the user will choose. When configuring your Web-SSO, you have to: |
|
|
|
|
|
|
|
|
|
* choose the ldap attributes you want to use to manage accounting and |
|
|
|
|
authorization. |
|
|
|
|
* create Perl expressions to define user groups (using ldap attributes) |
|
|
|
|
* create an array foreach virtual host associating URI regular expressions and |
|
|
|
|
Perl expressions to use to grant access. |
|
|
|
|
|
|
|
|
|
Example (See Lemonldap::NG::Common::Conf(3) to see how configuration is stored) |
|
|
|
|
|
|
|
|
|
* Exported variables : |
|
|
|
|
|
|
|
|
|
# Custom-Name => LDAP attribute |
|
|
|
|
cn => cn |
|
|
|
|
departmentUID => departmentUID |
|
|
|
|
login => uid |
|
|
|
|
|
|
|
|
|
* User groups : |
|
|
|
|
|
|
|
|
|
# Custom-Name => group definition |
|
|
|
|
group1 => { $departmentUID eq "unit1" or $login = "xavier.guimard" } |
|
|
|
|
|
|
|
|
|
* Area protection: |
|
|
|
|
|
|
|
|
|
# Each VirtualHost has its own configuration |
|
|
|
|
# associating URL regexp to Perl expression |
|
|
|
|
* www1.domain.com : |
|
|
|
|
^/protected/.*$ => $groups =~ /\bgroup1\b/ |
|
|
|
|
default => accept |
|
|
|
|
}, |
|
|
|
|
* www2.domain.com => { |
|
|
|
|
^/site/.*$ => $uid eq "admin" or $groups =~ /\bgroup2\b/ |
|
|
|
|
^/(js|css) => accept |
|
|
|
|
default => deny |
|
|
|
|
}, |
|
|
|
|
}, |
|
|
|
|
|
|
|
|
|
2.2.1 - Performance |
|
|
|
|
|
|
|
|
|
You can use Perl expressions as complicated as you want and you can use all |
|
|
|
|
the exported LDAP attributes (and create your own attributes: with 'macros' |
|
|
|
|
mechanism) in groups evaluations, area protections or custom HTTP headers |
|
|
|
|
(you just have to call them with a "$"). |
|
|
|
|
|
|
|
|
|
You have to be careful when choosing your expressions: |
|
|
|
|
|
|
|
|
|
* groups and macros are evaluated each time a user is redirected to the portal |
|
|
|
|
* virtual host rules and exported headers are evaluated for each request on a |
|
|
|
|
protected area. |
|
|
|
|
|
|
|
|
|
It is also recommanded to use the groups mechanism to avoid having to evaluate |
|
|
|
|
a long expression at each HTTP request: |
|
|
|
|
|
|
|
|
|
# Virtual hosts : |
|
|
|
|
... |
|
|
|
|
www1.domain.com : |
|
|
|
|
^/protected/.*$ => $groups =~ /\bgroup1\b/ |
|
|
|
|
|
|
|
|
|
You can also use LDAP filters, or Perl expression or mixed expressions in |
|
|
|
|
groups definitions. Perl expressions has to be enclosed with {}: |
|
|
|
|
|
|
|
|
|
* group1 => (|(uid=xavier.guimard)(ou=unit1)) |
|
|
|
|
* group1 => {$uid eq "xavier.guimard" or $ou eq "unit1"} |
|
|
|
|
* group1 => (|(uid=xavier.guimard){$ou eq "unit1"}) |
|
|
|
|
|
|
|
|
|
It is also recommanded to use Perl expressions to avoid requiering the LDAP |
|
|
|
|
server more than 2 times per authentication. |
|
|
|
|
|
|
|
|
|
2.3 - Accounting |
|
|
|
|
|
|
|
|
|
2.3.1 - Logging portal access> |
|
|
|
|
|
|
|
|
|
Lemonldap::NG::Portal doesn't log anything by default, but it's easy to |
|
|
|
|
overload log method for normal portal access. |
|
|
|
|
|
|
|
|
|
2.3.2 - Logging application access |
|
|
|
|
|
|
|
|
|
Because a Web-SSO knows nothing about the protected application, it can't do |
|
|
|
|
more than logging URL. As Apache does this fine, L<Lemonldap::NG::Handler> |
|
|
|
|
gives it the name to used in logs. The whatToTrace parameter 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::NG can export HTTP headers either using a proxy or protecting |
|
|
|
|
directly the application. By default, the Auth-User field is used but you can |
|
|
|
|
change it using the exportedHeaders parameters (in the Manager, each virtual |
|
|
|
|
host as custom headers branch). This parameters contains an associative array |
|
|
|
|
per virtual host: |
|
|
|
|
|
|
|
|
|
* keys are the names of the choosen headers |
|
|
|
|
* values are Perl expressions where you can use user datas stored in the |
|
|
|
|
global storage. |
|
|
|
|
|
|
|
|
|
Example: |
|
|
|
|
|
|
|
|
|
* www1.domain.com : |
|
|
|
|
Auth-User => $uid |
|
|
|
|
Unit => $ou |
|
|
|
|
* www2.domain.com : |
|
|
|
|
Authorization => "Basic ".encode_base64($employeeNumber.":dummy") |
|
|
|
|
Remote-IP => $ip |
|
|
|
|
|
|
|
|
|
3 - SESSION STORAGE SYSTEM |
|
|
|
|
|
|
|
|
|
Lemonldap::NG use 3 levels of cache for authenticated users: |
|
|
|
|
|
|
|
|
|
* an Apache::Session::* module used by lemonldap::NG::Portal to store |
|
|
|
|
authenticated user parameters, |
|
|
|
|
* a Cache::Cache* module used by Lemonldap::NG::Handler to share authenticated |
|
|
|
|
users between Apache's threads or processus and of course between virtual |
|
|
|
|
hosts on the same machine |
|
|
|
|
* Lemonldap::NG::Handler variables : if the same user use the same thread or |
|
|
|
|
processus a second time, no request are needed to grant or refuse access. |
|
|
|
|
This is very efficient with HTTP/1.1 Keep-Alive system. |
|
|
|
|
|
|
|
|
|
So the number of request to the central storage is limited to 1 per active |
|
|
|
|
user each 10 minutes. |
|
|
|
|
|
|
|
|
|
Lemonldap::NG is very fast, but you can increase performance using a |
|
|
|
|
Cache::Cache module that does not use disk access. |
|
|
|
|
|
|
|
|
|
4 - LOGOUT SYSTEM |
|
|
|
|
|
|
|
|
|
Lemonldap::NG provides a single logout system: you can use it by adding a link |
|
|
|
|
to the portal with "logout=1" parameter in the portal (See |
|
|
|
|
Lemonldap::NG::Portal) and/or by configuring handler to intercept some URL |
|
|
|
|
(See Lemonldap::NG::Handler) directly in the manager interface or in apache |
|
|
|
|
configuration file. The logout system: |
|
|
|
|
* delete session in the global session storage, |
|
|
|
|
* replace Lemonldap::NG cookie by '', |
|
|
|
|
* delete handler caches only if logout action was started from a protected |
|
|
|
|
application and only in the current Apache server. So in other servers, |
|
|
|
|
session is still in cache for 10 minutes maximum if the user was connected |
|
|
|
|
on it in the last 10 minutes. |
|
|
|
|
|
|
|
|
|
5 - AUTHOR |
|
|
|
|
|
|
|
|
|
Xavier Guimard, x.guimard@free.fr |
|
|
|
|
|
|
|
|
|
6 - COPYRIGHT AND LICENSE |
|
|
|
|
|
|
|
|
|
Copyright (C) 2005-2007 by Xavier Guimard x.guimard@free.fr |
|
|
|
|
|
|
|
|
|
This library is free software; you can redistribute it and/or modify |
|
|
|
|
it under the 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. |
|
|
|
|
|
Xavier Guimard
12 years ago