378 lines
12 KiB
HTML
378 lines
12 KiB
HTML
<html>
|
|
<head>
|
|
<title>Lemonldap::NG</title>
|
|
<meta name="ROBOTS" content="INDEX,FOLLOW">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<meta name="DESCRIPTION" content="Lemonldap::NG installation">
|
|
<meta name="KEYWORDS" content="LEMONLDAP::NG, WEBSSO, WEB-SSO, LEMONLDAP, LEMONLDAP-NG, INSTALLATION">
|
|
<style>
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<h1 style="text-align: center;">Lemonldap::NG Installation</h1>
|
|
<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.</p>
|
|
|
|
<p>See <a href=overview.html>README file</a> to known how it works.</p>
|
|
|
|
<ol type="I">
|
|
<li><a href="#example">Example installation</a>
|
|
<ol type="1">
|
|
<li><a href="#prereq1">Prereq</a></li>
|
|
<li><a href="#ebuilding">Building</a></li>
|
|
<li><a href="#econf">Example configuration</a></li>
|
|
</ol>
|
|
</li>
|
|
<li><a href="#advanced">Advanced installation</a>
|
|
<ol type="1">
|
|
<li><a href="#prereq2">Prereq</a></li>
|
|
<li><a href="#softInst">Software installation</a></li>
|
|
<li><a href="#lmInst">Lemonldap::NG installation</a></li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
|
|
|
|
<ol type="I">
|
|
|
|
<h2><li><a name="example">Example installation</a></li></h2>
|
|
|
|
<p>The proposed example use a protected site named test.example.com. Non
|
|
authenticated users are redirected to auth.example.com.</p>
|
|
|
|
<ol type="1">
|
|
|
|
<h3><li><a name="prereq1">Prereq</a></li></h3>
|
|
|
|
<ol type="a">
|
|
<h4><li>Software</li></h4>
|
|
|
|
<p>To use Lemonldap::NG, you have to run a LDAP server and of course an Apache
|
|
server compiled with mod-perl (version 1.3 or 2.x). Generaly, the version of
|
|
Apache proposed with your Linux distribution match, but some distributions used
|
|
an experimental version of mod_perl with Apache2 (mod_perl-1.99) which does
|
|
not work with Lemonldap::NG. With such distributions (like Debian-3.1), you
|
|
have to use Apache-1.3 or to use a mod_perl backport (www.backports.org
|
|
package for Debian works fine).</p>
|
|
|
|
<h4><li>Perl prereq</li></h4>
|
|
|
|
<dl>
|
|
<dt><b>Perl modules :</b></dt>
|
|
<dd>
|
|
<p>Apache::Session, Net::LDAP, MIME::Base64, CGI, LWP::UserAgent, Cache::Cache,
|
|
DBI, XML::Simple, SOAP::Lite (only if you want to use SOAP with the manager)</p>
|
|
</dd>
|
|
|
|
<dt><b>With Debian :</b></dt>
|
|
<dd>
|
|
<pre>
|
|
apt-get install libapache-session-perl libnet-ldap-perl libcache-cache-perl \
|
|
libdbi-perl perl-modules libwww-perl libcache-cache-perl \
|
|
libxml-simple-perl
|
|
</pre>
|
|
<p>If you want to use SOAP with the manager :</p>
|
|
<pre>
|
|
apt-get install libsoap-lite-perl
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
</ol>
|
|
|
|
<h3><li><a name="ebuilding">Building</a></li></h3>
|
|
|
|
<ol type="a">
|
|
|
|
<h4><li>Complete installation</li></h4>
|
|
<pre>
|
|
$ tar xzf lemonldap-ng-*.tar.gz
|
|
$ cd lemonldap-ng-*
|
|
$ make && make test
|
|
$ sudo make install
|
|
$ make example
|
|
</pre>
|
|
|
|
<h4><li>Installation on Debian</li></h4>
|
|
<pre>
|
|
$ tar xzf lemonldap-ng-*.tar.gz
|
|
$ cd lemonldap-ng-*
|
|
$ debuild # or fakeroot dpkg-buildpackage
|
|
$ sudo dpkg -i ../lemonldap-ng*.deb
|
|
</pre>
|
|
|
|
</ol>
|
|
|
|
<h3><li><a name="econf">Example configuration</a></li></h3>
|
|
|
|
<p>After build, you have new files in the example/ directory
|
|
(<code>/usr/share/doc/lemonldap-ng/example</code> with Debian). You just have
|
|
to include this file in Apache configuration :</p>
|
|
|
|
<ul>
|
|
<li>in httpd.conf (with Apache-1.3.x)
|
|
<pre>
|
|
include /path/to/lemonldap-ng/source/example/apache.conf
|
|
</pre>
|
|
</li>
|
|
|
|
<li>or with Apache2
|
|
<pre>
|
|
include /path/to/lemonldap-ng/source/example/apache2.conf
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Modify your /etc/hosts file to include :</p>
|
|
|
|
<pre>
|
|
127.0.0.2 auth.example.com
|
|
127.0.0.3 test.example.com
|
|
127.0.0.4 manager.example.com
|
|
</pre>
|
|
|
|
<p>and restart Apache.</p>
|
|
|
|
<p>Before the example works, you have to set your LDAP settings. There are two
|
|
ways to do it :
|
|
|
|
<ul>
|
|
<li>Connect to <a href="http://manager.example.com/">http://manager.example.com/</a>
|
|
and edit the corresponding parameters in "general parameters"</li>
|
|
|
|
<li>Edit <code>/path/to/lemonldap-ng/source/example/conf/lmConfig-1</code> and
|
|
specify your LDAP settings.</li>
|
|
</ul>
|
|
|
|
<p>If you don't set managerDn and managerPassword, Lemonldap::NG will
|
|
use an anonymous bind to find user dn.</p>
|
|
|
|
<p>WARNINGS :</p>
|
|
|
|
<ul>
|
|
<li> only few parameters can be set by hand in the configuration file. You have
|
|
to use the manager to change configuration, but since the example is yet
|
|
configured, you can edit directly the file</li>
|
|
<li> each new configuration is saved by the manager in a new file (or a new
|
|
record with DBI) so you can recover an old configuration by removing</li>
|
|
</ul>
|
|
|
|
<p>Next, try to connect to <a href="http://test.example.com/">http://test.example.com/</a>.
|
|
You'll be redirect to auth.example.com. Try to authenticate yourself with a
|
|
valid account and the protected page will appear. You will find other
|
|
explanations on this page.</p>
|
|
|
|
</ol>
|
|
|
|
<h2><li><a name="advanced">Advanced installation</a></li></h2>
|
|
|
|
<ol type="1">
|
|
|
|
<h3><li><a name="prereq2">Prereq</a></li></h3>
|
|
|
|
<ol type="a">
|
|
|
|
<h4><li>Apache</li></h4>
|
|
|
|
<p>To use Lemonldap::NG, you have to run a LDAP server and of course an Apache
|
|
server compiled with mod-perl (version 1.3 or 2.x). Generaly, the version of
|
|
Apache proposed with your Linux distribution match, but some distributions used
|
|
an experimental version of mod_perl with Apache2 (mod_perl-1.99) which does
|
|
not work with Lemonldap::NG. With such distributions (like Debian-3.1), you
|
|
have to use Apache-1.3 or to use a mod_perl backport (www.backports.org
|
|
package for Debian works fine).</p>
|
|
|
|
<p>For Apache2, you can use both mpm-worker and mpm-prefork. Mpm-worker works
|
|
faster and Lemonldap::NG use the thread system for best performance. If you
|
|
have to use mpm-prefork (for example if you use PHP), Lemonldap::NG will work
|
|
anyway.</p>
|
|
|
|
<p>You can use Lemonldap::NG in an heterogene world : the authentication portal and
|
|
the manager can work in any version of Apache 1.3 or more even if mod_perl is
|
|
not compiled, with ModPerl::Registry or not... Only the handler (site protector)
|
|
need mod_perl. The different handlers can run on different servers with
|
|
different versions of Apache/mod_perl.</p>
|
|
|
|
<h4><li>Perl Prereq</li></h4>
|
|
|
|
<p>Warning : Handler and Portal parts both need Lemonldap::NG::Manager components
|
|
to access to configuration.</p>
|
|
|
|
<dl>
|
|
<dt>Manager :</dt>
|
|
<dd><p>CGI, XML::Simple, DBI, LWP::UserAgent (and SOAP::Lite if you want to use SOAP)</p>
|
|
|
|
<p>With Debian :</p>
|
|
<pre>
|
|
# apt-get install perl-modules libxml-simple-perl libdbi-perl libwww-perl
|
|
</pre>
|
|
<p>And if you want to use SOAP :</p>
|
|
<pre>
|
|
# apt-get install libsoap-lite-perl
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>Portal :</dt>
|
|
<dd><p>Apache::Session, Net::LDAP, CGI, Lemonldap::NG::Manager</p>
|
|
|
|
<p>With Debian :</p>
|
|
<pre>
|
|
# apt-get install libapache-session-perl libnet-ldap-perl perl-modules
|
|
</pre>
|
|
</dd>
|
|
|
|
<dt>Handler :</dt>
|
|
<dd><p>Apache::Session, LWP::UserAgent, Cache::Cache, Lemonldap::NG::Manager</p>
|
|
|
|
<p>With Debian :</p>
|
|
<pre>
|
|
# apt-get install libapache-session-perl libwww-perl libcache-cache-perl
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
</ol>
|
|
|
|
<h3><li><a name="softInst">Software installation</a></li></h3>
|
|
|
|
<p>If you just want to install a handler or a portal or a manager :</p>
|
|
|
|
<pre>
|
|
$ tar xzf lemonldap-ng-*.tar.gz
|
|
$ cd lemonldap-ng-*/Lemonldap-NG-(Portal|Handler|Manager)
|
|
$ perl Makefile.PL && make && make test
|
|
$ sudo make install
|
|
</pre>
|
|
|
|
<p>else for a complete install :</p>
|
|
<pre>
|
|
$ tar xzf lemonldap-ng-*.tar.gz
|
|
$ cd lemonldap-ng-*
|
|
$ make && make test
|
|
$ sudo make install
|
|
</pre>
|
|
|
|
<p>See prereq in Exeample installation</p>
|
|
|
|
<h3><li><a name="lmInst">Lemonldap::NG installation</a></li></h3>
|
|
|
|
<ol type="a">
|
|
|
|
<h4><li>Databases configuration</li></h4>
|
|
|
|
<h5>Lemonldap::NG Configuration database</h5>
|
|
|
|
<p>If you use DBI or another system to share Lemonldap::NG configuration, you have
|
|
to initialize the database. An example is given in example/lmConfig.mysql for
|
|
MySQL.</p>
|
|
<!-- TODO: File -->
|
|
|
|
<h5>Apache::Session database</h5>
|
|
|
|
<p>The choice of Apache::Session::* module is free. See Apache::Session::Store::*
|
|
or Apache::Session::* to know how to configure the module. For example, if you
|
|
want to use Apache::Session::MySQL, you can create the database like this :</p>
|
|
|
|
<pre>
|
|
CREATE DATABASE sessions (
|
|
id char(32),
|
|
a_session text
|
|
);
|
|
</pre>
|
|
|
|
<h4><li>Manager configuration</li></h4>
|
|
|
|
<p>Copy example/manager.cgi and personalize it if you want (see
|
|
Lemonldap::NG::Manager). You have to set in particular configStorage. For
|
|
example with MySQL :</p>
|
|
|
|
<pre>
|
|
$my $manager = Lemonldap::NG::Manager->new ( {
|
|
dbiChain => "DBI:mysql:database=mybase;host=1.2.3.4",
|
|
dbiUser => "lemonldap-ng",
|
|
dbiPassword => "mypass",
|
|
} );
|
|
</pre>
|
|
|
|
<p>You can securise Manager access with Lemonldap::NG like any other site (after
|
|
configuring it) or with Apache. Example :</p>
|
|
|
|
<pre>
|
|
SSLEngine On
|
|
Order Deny, Allow
|
|
Deny from all
|
|
Allow from admin-network/netmask
|
|
AuthType Basic
|
|
...
|
|
</pre>
|
|
|
|
<h4><li>Configuration edition</li></h4>
|
|
|
|
<p>Connect to the manager with your browser start configure your Web-SSO. You have
|
|
to set at least some parameters :</p>
|
|
|
|
<h5>General parameters</h5>
|
|
|
|
<p>Main parameters :</p>
|
|
<ul>
|
|
<li> <b>Authentication parameters -> portal</b> : URL to access to the authentication portal</li>
|
|
<li> <b>Domain</b> : the cookie domain. Unless some protected VirtualHosts
|
|
are not under it, you have to use Lemonldap::NG::Portal::CDA and
|
|
Lemonldap::NG::Handler::CDA </li>
|
|
<li> <b>LDAP parameters -> LDAP Server</b></li>
|
|
<li> <b>LDAP parameters -> LDAP Accout and password</b> : required only if anonymous binds are not accepted</li>
|
|
<li> <b>Session Storage -> Apache::Session module</b> : how to store user sessions. You can use all module that inherit
|
|
from Apache::Session like Apache::Session::MySQL</li>
|
|
<li> <b>Session Storage -> Apache::Session Module parameters</b> : see Apache::Session::<Choosen module></li>
|
|
</ul>
|
|
|
|
<h5>User groups</h5>
|
|
|
|
<p>Use the "New Group" button to add your first group. On the left, set the
|
|
keyword which will be used later and set on the right the corresponding rule.
|
|
you can use :</p>
|
|
|
|
<ul>
|
|
<li> an LDAP filter (it will be tested with the user uid)</li>
|
|
<li> or a Perl condition enclosed with <b>{}</b>. All variables declared in
|
|
"General parameters -> LDAP attributes" or "macros"
|
|
can be used with a "<b>$</b>". For example :
|
|
<pre>
|
|
MyGroup => { $uid eq "foo" or $uid eq "bar" }
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
|
|
<h5>Virtual hosts</h5>
|
|
|
|
<p>You have to create a virtual host for each Apache host (virtual or real)
|
|
protected by Lemonldap::NG even if just a sub-directory is protected. Else,
|
|
user who want to access to the protected area will be rejected with a "500
|
|
Internal Server Error" message and the apache logs will explain the problem.</p>
|
|
|
|
<p>Each virtual host has 2 groups of parameters :</p>
|
|
|
|
<ul>
|
|
<li> Headers : the headers added to the apache request. Default :
|
|
<pre>
|
|
Auth-User => $uid
|
|
</pre>
|
|
</li>
|
|
<li> Rules : subdivised in 2 categories :
|
|
<ul>
|
|
<li><b>default</b> : the default rule</li>
|
|
<li>personalized rules : association of a Perl regular expression and a
|
|
condition. For example :
|
|
<pre>
|
|
^/restricted.*$ / $groups =~ /\bMyGroup\b/
|
|
</pre>
|
|
</li>
|
|
</ul>
|
|
</ol>
|
|
</ol>
|
|
</ol>
|
|
</body>
|
|
</html>
|
|
|