475 lines
16 KiB
HTML
475 lines
16 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="fr" xml:lang="fr">
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org" />
|
|
|
|
<title>Lemonldap::NG documentation: 1-Overview.html</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
|
|
<style type="text/css">
|
|
/*<![CDATA[*/
|
|
body{
|
|
background: #ddd;
|
|
font-family: sans-serif;
|
|
font-size: 11pt;
|
|
padding: 0 50px;
|
|
}
|
|
div.main-content{
|
|
padding: 10px;
|
|
background: #fff;
|
|
border: 2px #ccc solid;
|
|
}
|
|
a{
|
|
text-decoration: none;
|
|
}
|
|
p.footer{
|
|
text-align: center;
|
|
margin: 5px 0 0 0;
|
|
}
|
|
.heading-1{
|
|
text-align: center;
|
|
color: orange;
|
|
font-variant: small-caps;
|
|
font-size: 20pt;
|
|
}
|
|
.heading-1-1{
|
|
color: orange;
|
|
font-size: 14pt;
|
|
border-bottom: 2px #ccc solid;
|
|
}
|
|
pre{
|
|
background: #eee;
|
|
border: 2px #ccc solid;
|
|
padding: 5px;
|
|
border-left: 10px #ccc solid;
|
|
}
|
|
ul.star li{
|
|
list-style-type: square;
|
|
}
|
|
/*]]>*/
|
|
</style>
|
|
<style type="text/css">
|
|
/*<![CDATA[*/
|
|
div.c1 {text-align: center}
|
|
/*]]>*/
|
|
</style>
|
|
</head>
|
|
|
|
<body>
|
|
<div class="main-content">
|
|
<h2 class="heading-1"><span id=
|
|
"HLemonLDAP3A3ANG">LemonLDAP::NG</span></h2>
|
|
|
|
<p class="paragraph"></p>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. 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.
|
|
|
|
<p class="paragraph"></p>Lemonldap::NG is a complete rewrite of Lemonldap.
|
|
All components needed to use it and to aminister it are included in the
|
|
tarball. Contrary, all modules developed for Lemonldap may not work with
|
|
Lemonldap::NG.
|
|
|
|
<p class="paragraph"></p>
|
|
|
|
<ul>
|
|
<li><a href="#HArchitecture">Architecture</a></li>
|
|
|
|
<li><a href="#HKinematics">Kinematics</a></li>
|
|
|
|
<li>
|
|
<a href=
|
|
"#HAuthentication2CAuthorizationandAccountingmechanisms">Authentication,
|
|
Authorization and Accounting mechanisms</a>
|
|
|
|
<ul>
|
|
<li><a href="#HAuthentication">Authentication</a></li>
|
|
|
|
<li>
|
|
<a href="#HAuthorization">Authorization</a>
|
|
|
|
<ul>
|
|
<li><a href="#HPerformance">Performance</a></li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#HAccounting">Accounting</a>
|
|
|
|
<ul>
|
|
<li><a href="#HLoggingportalaccess">Logging portal
|
|
access</a></li>
|
|
|
|
<li><a href="#HLoggingapplicationaccess">Logging application
|
|
access</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li><a href="#HInstallation">Installation</a></li>
|
|
|
|
<li><a href="#HSessionstoragesystem">Session storage system</a></li>
|
|
|
|
<li><a href="#HAuthor">Author</a></li>
|
|
|
|
<li><a href="#HCopyrightandlicence">Copyright and licence</a></li>
|
|
</ul>
|
|
|
|
<h3 class="heading-1-1"><span id="HArchitecture">Architecture</span></h3>
|
|
|
|
<p class="paragraph"></p>Lemonldap::NG est composed by 3 elements and 3
|
|
databases :
|
|
|
|
<p class="paragraph"></p>
|
|
|
|
<div class="c1"><img src="lemonldap-ng-architecture.png" alt=
|
|
"lemonldap-ng-architecture.png" /></div>
|
|
|
|
<p class="paragraph"></p>Lemonldap::NG components :
|
|
|
|
<ul class="star">
|
|
<li>the Manager used to manage Lemonldap::NG configuration,</li>
|
|
|
|
<li>the Portal used to authenticate users,</li>
|
|
|
|
<li>Apache modules used to protect applications. They can protect an
|
|
Apache area which can be a reverse-proxy. In this case, it is
|
|
recommended to securise the link between the reverse-proxy and the
|
|
hidden server because access can be done without authentication to this
|
|
server. A simple .htaccess or an SSL handshake can be used depending on
|
|
the security level of the host network.</li>
|
|
</ul>Three databases are required :
|
|
|
|
<ul class="star">
|
|
<li>the configuration database : by default, it's a simple directory,
|
|
but you can use a network database to share configuration if all the
|
|
Lemonldap::NG components aren't on the same physical server,</li>
|
|
|
|
<li>the LDAP server : in addition to the authentications (that can be
|
|
done by another mechanism as X509 certificates), it is used to load user
|
|
attributes and calculate the rights,</li>
|
|
|
|
<li>the sessions database : Lemonldap::NG uses Apache::Session modules
|
|
to manage sessions. By default, it uses Apache::Session::File module and
|
|
so, this database is a simple directory. Using Apache::Session::MySQL
|
|
for example, the database can be used on a network so Lemonldap::NG can
|
|
works on several physical servers.</li>
|
|
</ul>
|
|
|
|
<h3 class="heading-1-1"><span id="HKinematics">Kinematics</span></h3>
|
|
|
|
<p class="paragraph"></p>
|
|
|
|
<div class="c1"><img src="lemonldap-ng-cinematique.png" alt=
|
|
"lemonldap-ng-cinematique.png" /></div>
|
|
|
|
<p class="paragraph"></p>Detail of operations :
|
|
|
|
<ul class="star">
|
|
<li>1 and 2 : non-authenticated users (ie without valid cookie) are
|
|
redirected to the portal,</li>
|
|
|
|
<li>3 : authentication request (login password validated on LDAP server
|
|
or other mechanism),</li>
|
|
|
|
<li>4 : recovery ok user attributes,</li>
|
|
|
|
<li>5 : calculation of the additional attributes asked in the
|
|
configuration (macros and groups) and storage of the user datas in the
|
|
sessions database,</li>
|
|
|
|
<li>6 : cookie generation and redirection to the asked URL,</li>
|
|
|
|
<li>7 : interception of the cookie by the agent of protection (Apache
|
|
module) and recovery of the user datas,</li>
|
|
|
|
<li>8 : checking of the access authorization to the asked URL and
|
|
transmission to the application (real application or reverse-proxy) if
|
|
granted,</li>
|
|
|
|
<li>9 and 10 : other request are treated directly with the use datas
|
|
stored in the local cache. Access grant is calculated at each
|
|
request.</li>
|
|
</ul>When the authenticated user tries to access to another protected
|
|
server, only phases 7 to 10 are replayed in all transparency for the user.
|
|
|
|
<h3 class="heading-1-1"><span id=
|
|
"HAuthentication2CAuthorizationandAccountingmechanisms">Authentication,
|
|
Authorization and Accounting mechanisms</span></h3>
|
|
|
|
<p class="paragraph"></p>All parameters described here can be edited by
|
|
the administration interface (See <span class="wikiexternallink"><a href=
|
|
"http://lemonldap.objectweb.org/NG/ManagerDemo/en/">Manager
|
|
demonstration</a></span>).
|
|
|
|
<h4 class="heading-1-1-1"><span id=
|
|
"HAuthentication">Authentication</span></h4>
|
|
|
|
<p class="paragraph"></p>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).
|
|
|
|
<p class="paragraph"></p>Lemonldap 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.
|
|
|
|
<p class="paragraph"></p>You have to manage life of sessions by yourself
|
|
since Lemonldap::NG knows nothing about the L 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.
|
|
|
|
<p class="paragraph"></p>By default, a session stay 10 minutes in the
|
|
local storage, so in the worst case, a user is authorized 10 minutes after
|
|
he lost his rights.
|
|
|
|
<h4 class="heading-1-1-1"><span id=
|
|
"HAuthorization">Authorization</span></h4>
|
|
|
|
<p class="paragraph"></p>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:
|
|
|
|
<ul class="star">
|
|
<li>choose the ldap attributes you want to use to manage accounting and
|
|
authorization.</li>
|
|
|
|
<li>create Perl expressions to define user groups (using ldap
|
|
attributes)</li>
|
|
|
|
<li>create an array foreach virtual host associating URI regular
|
|
expressions and Perl expressions to use to grant access.</li>
|
|
</ul>Example (See Lemonldap::NG::Manager::Conf(3) to see how configuration
|
|
is stored) :
|
|
|
|
<ul class="star">
|
|
<li>Exported variables :</li>
|
|
</ul>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
# Custom-Name => LDAP attribute
|
|
cn => cn
|
|
departmentUID => departmentUID
|
|
login => uid
|
|
</pre>
|
|
</div>
|
|
|
|
<ul class="star">
|
|
<li>User groups :</li>
|
|
</ul>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
# Custom-Name => group definition
|
|
group1 => { $departmentUID eq <span class=
|
|
"java-quote">"unit1"</span> or $login = <span class=
|
|
"java-quote">"user1"</span> }
|
|
</pre>
|
|
</div>
|
|
|
|
<ul class="star">
|
|
<li>Area protection: each VirtualHost has its own configuration
|
|
associating URL regexp to Perl expression
|
|
|
|
<ul class="star">
|
|
<li>www1.domain.com :</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
^/<span class=
|
|
"java-keyword">protected</span>/.*$ => $groups =~ /\bgroup1\b/
|
|
<span class="java-keyword">default</span> => accept
|
|
</pre>
|
|
</div>
|
|
|
|
<ul class="star">
|
|
<li>www2.domain.com :</li>
|
|
</ul>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
^/site/.*$ => $uid eq <span class=
|
|
"java-quote">"admin"</span> or $groups =~ /\bgroup2\b/
|
|
^/(js|css) => accept
|
|
<span class="java-keyword">default</span> => deny
|
|
</pre>
|
|
</div>
|
|
|
|
<p class="paragraph"></p>Note: \b means start or end of a word in PCRE
|
|
(Perl Compatible Regular Expressions)
|
|
|
|
<h5 class="heading-1-1-1-1"><span id=
|
|
"HPerformance">Performance</span></h5>
|
|
|
|
<p class="paragraph"></p>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
|
|
"$").
|
|
|
|
<p class="paragraph"></p>ou have to be careful when choosing your
|
|
expressions:
|
|
|
|
<ul class="star">
|
|
<li>groups and macros are evaluated each time a user is redirected to
|
|
the portal,</li>
|
|
|
|
<li>virtual host rules and exported headers are evaluated for each
|
|
request on a protected area.</li>
|
|
</ul>It is also recommanded to use the groups mechanism to avoid having to
|
|
evaluate a long expression at each HTTP request :
|
|
|
|
<div class="code">
|
|
<pre>
|
|
^/<span class=
|
|
"java-keyword">protected</span>/.*$ => $groups =~ /\bgroup1\b/
|
|
</pre>
|
|
</div><br />
|
|
<br />
|
|
You can also use LDAP filters, or Perl expression or mixed expressions in
|
|
groups definitions. Perl expressions has to be enclosed with {} :
|
|
|
|
<div class="code">
|
|
<pre>
|
|
group1 => (|(uid=xavier.guimard)(ou=unit1))
|
|
group1 => {$uid eq <span class=
|
|
"java-quote">"xavier.guimard"</span> or $ou eq <span class=
|
|
"java-quote">"unit1"</span>}
|
|
group1 => (|(uid=xavier.guimard){$ou eq <span class=
|
|
"java-quote">"unit1"</span>})
|
|
</pre>
|
|
</div>
|
|
|
|
<p class="paragraph"></p>It is also recommanded to use Perl expressions to
|
|
avoid requiering the LDAP server more than 2 times per authentication.
|
|
|
|
<h4 class="heading-1-1-1"><span id="HAccounting">Accounting</span></h4>
|
|
|
|
<h5 class="heading-1-1-1-1"><span id="HLoggingportalaccess">Logging portal
|
|
access</span></h5>
|
|
|
|
<p class="paragraph"></p>Lemonldap::NG::Portal doesn't log anything by
|
|
default, but it's easy to overload log method for normal portal access.
|
|
|
|
<h5 class="heading-1-1-1-1"><span id="HLoggingapplicationaccess">Logging
|
|
application access</span></h5>
|
|
|
|
<p class="paragraph"></p>Because a Web-SSO knows nothing about the
|
|
protected application, it can't do more than logging URL. As Apache does
|
|
this fine, Lemonldap::NG::Handler(3) gives it the name to used in logs.
|
|
The whatToTrace parameter indicates which variable Apache has to use ($uid
|
|
by default).
|
|
|
|
<p class="paragraph"></p>The real accounting has to be done by the
|
|
application itself which knows the result of SQL transaction for example.
|
|
|
|
<p class="paragraph"></p>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 :
|
|
|
|
<ul class="star">
|
|
<li>keys are the names of the choosen headers,</li>
|
|
|
|
<li>values are Perl expressions where you can use user datas stored in
|
|
the global storage.</li>
|
|
</ul>Example:
|
|
|
|
<ul class="star">
|
|
<li>www1.domain.com :</li>
|
|
</ul>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
Auth-User => $uid
|
|
Unit => $ou
|
|
</pre>
|
|
</div>
|
|
|
|
<ul class="star">
|
|
<li>www2.domain.com :</li>
|
|
</ul>
|
|
|
|
<div class="code">
|
|
<pre>
|
|
Authorization => <span class=
|
|
"java-quote">"Basic "</span>.encode_base64($employeeNumber.<span class=
|
|
"java-quote">":dummy"</span>)
|
|
Remote-IP => $ip
|
|
</pre>
|
|
</div>
|
|
|
|
<h3 class="heading-1-1"><span id="HInstallation">Installation</span></h3>
|
|
|
|
<p class="paragraph"></p>Warnings :
|
|
|
|
<ul class="star">
|
|
<li>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.</li>
|
|
|
|
<li>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.</li>
|
|
|
|
<li>Lemonldap::NG configuration has to be edited using the manager
|
|
unless you know exactly what you are doing. The parameters discussed
|
|
below are all in the configuration tree.</li>
|
|
</ul>See <span class="wikilink"><a href="3-Table-of-contents.html">the
|
|
full documentation page</a></span> for a complete installation procedure.
|
|
|
|
<h3 class="heading-1-1"><span id="HSessionstoragesystem">Session storage
|
|
system</span></h3>
|
|
|
|
<p class="paragraph"></p>Lemonldap::NG use 3 levels of cache for
|
|
authenticated users :
|
|
|
|
<ul class="star">
|
|
<li>an Apache::Session::* module used by lemonldap::NG::Portal to store
|
|
authenticated user parameters,</li>
|
|
|
|
<li>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,</li>
|
|
|
|
<li>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.</li>
|
|
</ul>So the number of request to the central storage is limited to 1 per
|
|
active user each 10 minutes.
|
|
|
|
<p class="paragraph"></p>Lemonldap::NG is very fast, but you can increase
|
|
performance using a Cache::Cache module that does not use disk access.
|
|
|
|
<h3 class="heading-1-1"><span id="HAuthor">Author</span></h3>
|
|
|
|
<p class="paragraph"></p>Xavier Guimard, <x.guimard@free.fr>
|
|
|
|
<h3 class="heading-1-1"><span id="HCopyrightandlicence">Copyright and
|
|
licence</span></h3>
|
|
|
|
<p class="paragraph"></p>Copyright © 2005-2007 by Xavier Guimard
|
|
<x.guimard@free.fr>
|
|
|
|
<p class="paragraph"></p>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.
|
|
</div>
|
|
|
|
<p class="footer"><a href="index.html">Index</a></p>
|
|
</body>
|
|
</html>
|