INSTALL 9.5 KB
Newer Older
1 2 3 4 5 6 7 8 9
                          LEMONLDAP::NG INSTALLATION

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.

See README file to known how it works.

10 11 12
----------------------
I - QUICK INSTALLATION
----------------------
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33

The proposed example use a protected site named test.example.com. Non
authenticated users are redirected to auth.example.com.

1.1 - PREREQ
------------

1.1.1 - Software

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).

1.1.2 - Perl prereq

Perl modules:
  Apache::Session, Net::LDAP, MIME::Base64, CGI, LWP::UserAgent, Cache::Cache,
34
  DBI, XML::Simple, SOAP::Lite, HTML::Template, XML::LibXML, XML::LibXSLT
35 36 37 38

With Debian:
  apt-get install libapache-session-perl libnet-ldap-perl libcache-cache-perl \
                  libdbi-perl perl-modules libwww-perl libcache-cache-perl \
39
                  libxml-simple-perl libhtml-template-perl libsoap-lite-perl \
40
                  libxml-libxml-perl libxml-libxslt-perl
41 42 43 44 45 46 47 48 49 50

1.2 - BUILDING
--------------

1.2.1 - Complete install

  $ tar xzf lemonldap-ng-*.tar.gz
  $ cd lemonldap-ng-*
  $ make && make test
  $ sudo make install
51 52 53

By default, all is installed in /usr/local/lemonldap-ng except Perl libraries
which are installed in a directory included in @INC.
54 55 56 57 58 59

1.2.2 - Install on Debian

  $ tar xzf lemonldap-ng-*.tar.gz
  $ cd lemonldap-ng-*
  $ debuild
60
  $ sudo dpkg -i ../*lemonldap-ng*.deb
61

62 63 64
Here, all is installed in /var/lib/lemonldap-ng, /etc/lemonldap-ng except Perl
libraries which are installed in /usr/share/perl5/Lemonldap/NG/

65 66 67
1.3 - EXAMPLE CONFIGURATION
---------------------------

68
If you have build Debian packages, configuration is done by Debconf. See
69
/usr/share/doc/liblemonldap-ng-common/README.Debian to use it.
70

71 72 73 74 75 76 77 78 79 80
After build, you have a new file named example/apache.conf. You just have to
include this file in Apache configuration:

  # in httpd.conf (with Apache1)
  include /path/to/lemonldap-ng/source/example/apache.conf
  # or in apache2.conf (with Apache2)
  include /path/to/lemonldap-ng/source/example/apache2.conf

Modify your /etc/hosts file to include:

81
  127.0.0.1 auth.example.com test1.example.com manager.example.com test2.example.com
82

83
Use a browser to connect to http://manager.example.com/ and specify your LDAP
84 85 86 87
settings. If you don't set managerDn and managerPassword, Lemonldap::NG will
use an anonymous bind to find user dn.

Next, restart Apache use your prefered browser and try to connect to
88
http://test1.example.com/. You'll be redirect to auth.example.com. Try
89 90 91
to authenticate yourself with a valid account and the protected page will
appear. You will find other explanations on this page.

92 93 94
the file /usr/local/lemonldap-ng/etc/storage.conf
(/etc/lemonldap-ng/storage.conf on Debian systems) can be modified to change
configuration database.
95 96 97 98 99

-------------------------
2 - ADVANCED INSTALLATION
-------------------------

100 101
It is recommended to install the example first then to adapt it.

102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
2.1 - PREREQ

2.1.1 - Apache

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).

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.

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.

2.1.2 - Perl prereq

Warning: Handler and Portal parts both need Lemonldap::NG::Manager components
to access to configuration.

Manager:
131 132 133
--------
Apache::Session, MIME::Base64, CGI, LWP::UserAgent, DBI, XML::Simple,
SOAP::Lite, XML::LibXML, XML::LibXSLT, Lemonldap::NG::Common
134 135 136 137 138 139 140

With Debian:
  apt-get install perl-modules libxml-simple-perl libdbi-perl libwww-perl
  # If you want to use SOAP
  apt-get install libsoap-lite-perl

Portal:
141 142 143
-------
Apache::Session, Net::LDAP, MIME::Base64, CGI, Cache::Cache, DBI, XML::Simple,
SOAP::Lite, HTML::Template, XML::LibXML, Lemonldap::NG::Common
144 145 146 147 148

With Debian:
  apt-get install libapache-session-perl libnet-ldap-perl perl-modules

Handler:
149 150 151
--------
Apache::Session, MIME::Base64, CGI, LWP::UserAgent, Cache::Cache, DBI,
XML::Simple, SOAP::Lite, Lemonldap::NG::Common
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172

With Debian:
  apt-get install libapache-session-perl libwww-perl libcache-cache-perl

2.2 - SOFTWARE INSTALLATION
---------------------------

If you just want to install a handler or a portal or a manager:

  $ tar xzf lemonldap-ng-*.tar.gz
  $ cd lemonldap-ng-*/Lemonldap-NG-(Portal|Handler|Manager)
  $ perl Makefile.PL && make && make test
  $ sudo make install

else for a complete install:

  $ tar xzf lemonldap-ng-*.tar.gz
  $ cd lemonldap-ng-*
  $ make && make test
  $ sudo make install

173
See prereq in §1.1.2
174

175 176
2.3 - LEMONLDAP::NG INSTALLATION
--------------------------------
177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208

2.3.1 - Database configuration

2.3.1.1 - Lemonldap::NG Configuration database

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.

2.3.1.2 - Apache::Session database

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:

  CREATE DATABASE sessions (
    id char(32),
    a_session text
  );

2.3.2 - Manager configuration

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:

  $my $manager = Lemonldap::NG::Manager->new ( {
                        dbiChain   => "DBI:mysql:database=mybase;host=1.2.3.4",
                        dbiUser    => "lemonldap-ng",
                        dbiPassword => "mypass",
                 } );

209
Securise Manager access with Apache: Lemonldap::NG does not securise the manager
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
itself yet:

  SSLEngine On
  Order Deny, Allow
  Deny from all
  Allow from admin-network/netmask
  AuthType Basic
  ...

After configuration, you can also protect the manager with an Lemonldap::NG
handler.

2.3.3 - Configuration edition

Connect to the manager with your browser start configure your Web-SSO. You have
to set at least some parameters:

a) General parameters :

 * Authentication parameters -> portal : URL to access to the authentication
                                         portal
 * Domain : the cookie domain. All protected VirtualHosts have to be under it

 * LDAP parameters -> LDAP Server

 * LDAP parameters -> LDAP Accout and password : required only if anonymous
                                                 binds are not accepted

 * Session Storage -> Apache::Session module : how to store user sessions.
                                               You can use all module that
                                               inherit from Apache::Session
                                               like Apache::Session::MySQL

 * Session Storage -> Apache::Session Module parameters :
                                        see Apache::Session::<Choosen module>

b) User groups :

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 :

 * an LDAP filter (it will be tested with the user uid)

or

 * a Perl condition enclosed with {}. All variables declared in "General
   parameters -> LDAP attributes" can be used with a "$". For example:
   MyGroup  /  { $uid eq "foo" or $uid eq "bar" }

c) Virtual hosts

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.

Each virtual host has 2 groups of parameters:

 * Headers: the headers added to the apache request. Default :
            Auth-User => $uid
 * Rules: subdivised in 2 categories:
          * default : the default rule
          * personalized rules: association of a Perl regular expression and
                                a condition. For example:
                                ^/restricted.*$  /  $groups =~ /\bMyGroup\b/


-------------
3 - DEBUGGING
-------------

Lemonldap::NG uses simply the Apache log system. So use LogLevel to choose
information to display.