lemonldap-ng/build/lemonldap-ng/doc/faq.html

579 lines
24 KiB
HTML

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.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 1 September 2005), see www.w3.org" />
<title>FAQ LEMONLDAP::NG</title>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
</head>
<body>
<div class="main-content">
<h2 class="heading-1"><span id=
"HLemonldap3A3ANGFrequentlyAskedQuestions">Lemonldap::NG Frequently Asked
Questions</span></h2>
<p class="paragraph"></p>
<ul>
<li>
<a href="#HGeneralquestions">General questions</a>
<ul>
<li><a href="#HWhatisaWebSSO3F">What is a Web-SSO ?</a></li>
<li><a href=
"#HWhatbringsLemonldap3A3ANGcomparedtotheotherWebSSO3F">What brings
Lemonldap::NG compared to the other Web-SSO ?</a></li>
</ul>
</li>
<li>
<a href="#HConfiguration">Configuration</a>
<ul>
<li><a href="#HWhattypeofconfigurationstoragehastobeused3F">What
type of configuration storage has to be used ?</a></li>
<li><a href="#HTheprovidedexampleworkswithHTTP2CbutnotwithHTTPS">The
provided example works with HTTP, but not with HTTPS.</a></li>
<li><a href="#HForwhatisusedthe22https22parameter3F">For what is
used the "https" parameter ?</a></li>
<li><a href="#HWhatisanautoprotectedCGI3F">What is an auto-protected
CGI ?</a></li>
<li><a href="#HHowtouseLemonldap3A3ANGwithActiveDirectory3F">How to
use Lemonldap::NG with Active-Directory ?</a></li>
<li><a href="#HHowtouseLemonldap3A3ANGasreverseproxy3F">How to use
Lemonldap::NG as reverse-proxy ?</a></li>
</ul>
</li>
<li>
<a href="#HOperation">Operation</a>
<ul>
<li><a href="#HWithwhatservesthehandlerlocalcache3F">With what
serves the handler local cache ?</a></li>
<li><a href=
"#HWhyhandlerslocalcachecannotbeconfiguredbythemanager3F">Why
handlers local cache can not be configured by the manager ?</a></li>
<li><a href=
"#HWhatisthe7E7ECrossDomainAuthentication7E7E28CDA293F">What is the
<i class="italic">Cross Domain Authentication</i> (CDA) ?</a></li>
<li><a href=
"#HHowworksthe7E7ECrossDomainAuthentication7E7E28CDA293F">How works
the <i class="italic">Cross Domain Authentication</i> (CDA)
?</a></li>
</ul>
</li>
<li>
<a href="#HAuthentication">Authentication</a>
<ul>
<li><a href="#HHowtochangeauthenticationscheme3F">How to change
authentication scheme ?</a></li>
</ul>
</li>
<li>
<a href="#HErroranddebugmessages">Error and debug messages</a>
<ul>
<li><a href="#H22IncorrectXML22">"Incorrect XML"</a></li>
<li><a href=
"#H22Byteorderisnotcompatible22ou22Magicnumbercheckingonstorablestringfailed22">
"Byte order is not compatible" ou "Magic number checking on storable
string failed"</a></li>
<li><a href=
"#H22Configurationisinoldformat2Cyou27vetomigrate2122">"Configuration
is in old format, you've to migrate !"</a></li>
<li><a href="#H22My3A3APackage3Agetconfiguration122">"My::Package:
get configuration 1"</a></li>
<li><a href="#H22My3A3APackage3Astoreconfiguration122">"My::Package:
store configuration 1"</a></li>
<li><a href="#H22My3A3APackage3ANocookiefound22">"My::Package: No
cookie found"</a></li>
<li><a href=
"#H22Redirect26lt3Bxxxx26gt3Btoportal28urlwas2F2922">"Redirect
&lt;x.x.x.x&gt; to portal (url was /)"</a></li>
<li><a href="#H22FoundaCDAidRedirecting22">"Found a CDA id.
Redirecting"</a></li>
<li><a href="#H22Usersomeonewasauthorizatedtoaccessto2F22">"User
someone was authorizated to access to /"</a></li>
<li><a href="#H22My3A3APackage3Aremovingcookie22">"My::Package:
removing cookie"</a></li>
<li><a href=
"#H22ErrorwhilereadingconfigurationwithglobalStorageOptionskey3A22">"Error
while reading configuration with globalStorageOptions key:"</a></li>
<li><a href=
"#H22UserrejectedbecauseVirtualHosttestexamplecomhasnoconfiguration22">
"User rejected because VirtualHost test.example.com has no
configuration"</a></li>
<li><a href=
"#H22Thecookiexxxxisn27tyetavailable3AObjectdoesnotexistinthedatastoreat2Fusr2Fshare2Fperl52FApache2FSession2FStore2FFilepmline905Cn22">
"The cookie xxxx isn't yet available: Object does not exist in the
data store at /usr/share/perl5/Apache/Session/Store/File.pm line
90.n"</a></li>
<li><a href=
"#H22Thecookiexxxxisn27tyetavailable3A7E7E26lt3BApache3A3ASessionerrormessage26gt3B7E7E">
"The cookie xxxx isn't yet available: <i class=
"italic">&lt;Apache::Session error message&gt;</i></a></li>
</ul>
</li>
</ul>
<h3 class="heading-1-1"><span id="HGeneralquestions">General
questions</span></h3>
<h4 class="heading-1-1-1"><span id="HWhatisaWebSSO3F">What is a Web-SSO
?</span></h4>
<p class="paragraph"></p>A SSO <i class="italic">(Single Sign On)</i> is a
system that is used to share authentications between many applications.
Users authentify themself only one time and is never prompted when he
tries to access to another application. Kerberos (used in Active
Directory) for example is a SSO. The problem with these systems is that in
addition to their heaviness, they apply only to internal networks and to
relatively homogeneous machines.
<p class="paragraph"></p>The Web-SSO is the bearing of this principle
restricted with the Web applications. The user is thus authenticated with
the first access to a protected Web application and the authentifications
are propagated when it changes application. The large advantage is whereas
the system is usable on Internet without pre-necessary on the stations
customers (they just have to accept session cookies). For example, when a
user reaches a Google letter-box, it is not authentified if it reaches the
groups management application or any other Google application.
<h4 class="heading-1-1-1"><span id=
"HWhatbringsLemonldap3A3ANGcomparedtotheotherWebSSO3F">What brings
Lemonldap::NG compared to the other Web-SSO ?</span></h4>
<ul class="star">
<li>Lemonldap::NG like lemonldap run as Perl Apache modules and offer
performances which make unperceivable the treatment of the access
control.</li>
<li>One of the other strong points of Lemonldap::NG is its capacity to
manage the rights in a centralized way: the standard SSO Kerberos or
CASE allow authentication share but delegate management access
authorizations to the applications. In the case of Lemonldap::NG,
management rights can be centralized completely, partly or at all for
each application&nbsp;: Lemonldap::NG provides a system of authorization
based on the sorting of the URL by regular expressions associated to
rules. It also provides HTTP headers containing any of the user LDAP
atributes to the remote application. The remote application can then
manage the traceability of the access and possibly authorization (see to
it <span class="wikiexternallink"><a href=
"http://wiki.lemonldap.objectweb.org/xwiki/bin/view/NG/Presentation#HMC3A9canismesd27authentification2Cd27autorisa%20tionetdetraC3A7abilitC3A9">
documentation AAA</a></span>).</li>
<li>Lemonldap::NG can publish every LDAP attributes or calculated
expressions issued from them. So applications can avoid consulting LDAP
server.</li>
<li>Lemonldap::NG treats all the hosted sites independently (virtual or
real): every application can so have its personalized HTTP headers.</li>
<li>Lemonldap::NG provide an web based administration interface simply
presenting the configuration, the access policy and the per sites
headers (see the <span class="wikiexternallink"><a href=
"http://lemonldap.objectweb.org/NG/ManagerDemo/fr/">demonstration</a></span>).
A restricted interface can also be used to show only some virtual hosts
(for reading and/or writing): the interface of administration can thus
be partially delegated.</li>
</ul>
<h3 class="heading-1-1"><span id=
"HConfiguration">Configuration</span></h3>
<h4 class="heading-1-1-1"><span id=
"HWhattypeofconfigurationstoragehastobeused3F">What type of configuration
storage has to be used ?</span></h4>
<p class="paragraph"></p>Lemonldap::NG provides 3 configuration storage
systems:
<ul class="star">
<li><strong class="strong">File</strong>: the most simple system, it can
be used only if all your servers share a file system. It can be used for
example if all virtual hosts are on the same server,</li>
<li><strong class="strong">DBI</strong>: <span class=
"wikiexternallink"><a href=
"http://www.linuxmanpages.com/man3/DBI.3pm.php">DBI(3)</a></span> is a
database access module for the Perl programming language. Used with
Lemonldap::NG, it permits to share configuration between servers that
can access to the same database. This is the recommended sheme on a
server network.</li>
<li><strong class="strong">SOAP</strong>: This system is not a real
storage system, but permits to a remote server to access to the
configuration by a single HTTP(S) connection. The SOAP server use File
or DBI to access to the real configuration and act as a proxy.</li>
</ul>
<h4 class="heading-1-1-1"><span id=
"HTheprovidedexampleworkswithHTTP2CbutnotwithHTTPS">The provided example
works with HTTP, but not with HTTPS.</span></h4>
<p class="paragraph"></p>In the redirection mechanism to the portal then
to the protected site, you have to indicate to the handler if users access
by HTTPS or HTTP to it. This is done by the <tt>https</tt> parameter. This
parameter has to be configured directly in the handlers is not accessible
by the manager interface:
<p class="paragraph"></p>
<pre>
__PACKAGE__-&gt;init ( {
localStorage =&gt; "Cache::FileCache",
localStorageOptions =&gt; {
'namespace' =&gt; 'MyNamespace',
'default_expires_in' =&gt; 600,
'directory_umask' =&gt; '007',
'cache_root' =&gt; '/tmp',
'cache_depth' =&gt; 5,
},
configStorage =&gt; {
type =&gt; 'File',
dirName =&gt; '/var/lib/lemonldap-ng/conf',
},
<strong class="strong">https =&gt; 1</strong>,
} );
</pre>
<h4 class="heading-1-1-1"><span id=
"HForwhatisusedthe22https22parameter3F">For what is used the "https"
parameter ?</span></h4>
<p class="paragraph"></p>This parameter is used only in authentication
portal redirections. It is just used to indicate to the portal that after
authentification, the user must be redirected towards the application
using https and not http.
<h4 class="heading-1-1-1"><span id="HWhatisanautoprotectedCGI3F">What is
an auto-protected CGI ?</span></h4>
<p class="paragraph"></p>When you have just 1 Perl CGI to protect in a
VirtualHost, you can use an auto-protected CGI instead of using a
Lemonldap::NG handler:
<p class="paragraph"></p>
<pre>
use Lemonldap::NG::Handler::CGI;
my $cgi = Lemonldap::NG::Handler::CGI-&gt;new ( {
# same parameters than a Lemonldap::NG::Handler::SharedConf handler
}
);
$cgi-&gt;authenticate;
</pre>
<p class="paragraph"></p>In the example above, $cgi is a CGI(3) object.
The only difference is that it has some additional functions:
<ul class="star">
<li>authenticate : to call Lemonldap::NG authentication mechanism,</li>
<li>autorize : use it if you want to use the manager to manage the
access policy,</li>
<li>user : returns an hash table containing user parameters,</li>
<li>group : used to validate group permet de valider group
membership.</li>
</ul>This type of CGI is very usefull when rights can not be distinguish
by URL (fields in POST requests for example). See the
Lemonldap::NG::Handler::CGI(3) man page for more.
<h4 class="heading-1-1-1"><span id=
"HHowtouseLemonldap3A3ANGwithActiveDirectory3F">How to use Lemonldap::NG
with Active-Directory ?</span></h4>
<p class="paragraph"></p>Active-Directory uses <tt>cn</tt> field instead
of <tt>uid</tt> as unique identifier. You have so to modify Lemonldap::NG
configuration in 2 points&nbsp;:
<ol>
<li>the field <tt>cn</tt> (or <tt>samAccountName</tt>) has to be used to
find the user in the portal,</li>
<li>Apache has to use this field in logs.</li>
</ol>For the second point, you have to replace <tt>$uid</tt> by
<tt>$cn</tt> in the field "General Parameters -&gt; Attribute to use in
Apache's logs" (and to verify that this variable is an exported
attribute). The LDAP filter change needs to overload a subroutine in the
portail. This can be done so&nbsp;:
<p class="paragraph"></p>
<pre>
#!/usr/bin/perl
use Lemonldap::NG::Portal::SharedConf;
my $portal = Lemonldap::NG::Portal::SharedConf-&gt;new(
{
configStorage =&gt; {
type =&gt; 'File',
dirName =&gt; '/var/lib/lemonldap-ng/conf',
},
<strong class="strong">formateFilter =&gt; sub {</strong>
my $self = shift;
$self-&gt;{filter} = "(&amp;(cn=" . $self-&gt;{user} . ")(objectClass=person))";
PE_OK;
} # end of overload
}
);
</pre>
<h4 class="heading-1-1-1"><span id=
"HHowtouseLemonldap3A3ANGasreverseproxy3F">How to use Lemonldap::NG as
reverse-proxy ?</span></h4>
<p class="paragraph"></p>Lemonldap::NG protects Apache VirtualHosts. To
use it as reverse-proxy, you just have to configure Apache as
reverse-proxy&nbsp;:
<p class="paragraph"></p>
<pre>
# httpd.conf
&lt;VirtualHost *&gt;
ServerName MyApplication.com
PerlRequire MyFile
PerlHeaderParserHandler My::Package
ProxyPass / <span class="nobr"><a href=
"http://real-server/">http://real-server/</a></span>
ProxyPassReverse / <span class="nobr"><a href=
"http://real-server/">http://real-server/</a></span>
# You can also use mod_rewrite instead of mod_proxy
# RewriteEngine On
# RewriteRule /(.*)$ <span class="nobr"><a href=
"http://serveur-reel/$1">http://serveur-reel/$1</a></span> [P]
&lt;/VirtualHost&gt;
</pre>
<p class="paragraph"></p>If you prefer to use a Perl proxy, Lemonldap::NG
provides one (Lemonldap::NG::Handler::Proxy(3))
<h3 class="heading-1-1"><span id="HOperation">Operation</span></h3>
<h4 class="heading-1-1-1"><span id=
"HWithwhatservesthehandlerlocalcache3F">With what serves the handler local
cache ?</span></h4>
<p class="paragraph"></p>The handler local cache is used for 2 things :
<ul class="star">
<li>share configuration between Apache process : this avoid downloading
configuration for each new process. This is required for the reload
mechanism system that avoid restarting Apache,</li>
<li>share sessions between Apache process and threads : this avoid
having to request the central sessions storage for each hit. For example
with Apache::Session::MySQL, we transform TCP requests in file system
requests. This increase performances.</li>
</ul>
<h4 class="heading-1-1-1"><span id=
"HWhyhandlerslocalcachecannotbeconfiguredbythemanager3F">Why handlers
local cache can not be configured by the manager ?</span></h4>
<p class="paragraph"></p>The local cache has to be choosed nad configured
for each server: for example with the Cache::FileCache module, the storage
directory can be different. An other point is that the local storage can
not be reloaded without restarting Apache, but all parameters managed by
the manager can do it.
<h4 class="heading-1-1-1"><span id=
"HWhatisthe7E7ECrossDomainAuthentication7E7E28CDA293F">What is the
<i class="italic">Cross Domain Authentication</i> (CDA) ?</span></h4>
<p class="paragraph"></p>The Lemonldap::NG sessions propagation system is
based on cookies, but cookies are attached to a DNS domain. Lemonldap::NG
provides a system to bypass this restriction: you just have to use a
Lemonldap::NG::Portal::CDA portal and Lemonldap::NG::Handler::CDA handlers
in all protected sites outwards the portal DNS domain.
<h4 class="heading-1-1-1"><span id=
"HHowworksthe7E7ECrossDomainAuthentication7E7E28CDA293F">How works the
<i class="italic">Cross Domain Authentication</i> (CDA) ?</span></h4>
<p class="paragraph"></p>Lemonldap::NG::Portal::CDA portal detects if
required URL is in the same domain. If not, it adds a parameter to this
request. When the user returns to the protected application,
Lemonldap::NG::Handler::CDA agent detects this parameter et generate a
cookie in its domain.
<h3 class="heading-1-1"><span id=
"HAuthentication">Authentication</span></h3>
<h4 class="heading-1-1-1"><span id=
"HHowtochangeauthenticationscheme3F">How to change authentication scheme
?</span></h4>
<p class="paragraph"></p>Lemonldap::NG provides several authentication
modes (to use in the "authentification" field of the administration
interface)&nbsp;:
<ul class="star">
<li><strong class="strong">ldap</strong> : this is the default mode :
portal tries to connect to the LDAP server with the user
credentials,</li>
<li><strong class="strong">CAS</strong> : Lemonldap::NG portal becomes a
simple CAS proxy : if the user is not authenticated, it is redirected to
the CAS portal,</li>
<li><strong class="strong">SSL</strong> : in this scheme, authentication
is done by Apache by SSL. This is usefull to replace complete SSL
protection: only one SSL negociation is used instead,</li>
<li><strong class="strong">Apache</strong> : in this scheme,
authentication is done by Apache. For example with Kerberos, the Apache
Kerberos module protects only the portal. This increases performances
because only one Kerberos negociation has to be done for all protected
applications.</li>
</ul>
<h3 class="heading-1-1"><span id="HErroranddebugmessages">Error and debug
messages</span></h3>
<p class="paragraph"></p>Lemonldap::NG produces error and debug messages
logged by Apache (in error.log by default). You can adapt debug level by
setting LogLevel parameter in Apache configuration file.
<h4 class="heading-1-1-1"><span id="H22IncorrectXML22">"Incorrect
XML"</span></h4>
<p class="paragraph"></p>This messages appears when the manager cannot
load configuration. The real error can be found in Apache logs.
<h4 class="heading-1-1-1"><span id=
"H22Byteorderisnotcompatible22ou22Magicnumbercheckingonstorablestringfailed22">
"Byte order is not compatible" ou "Magic number checking on storable
string failed"</span></h4>
<p class="paragraph"></p>This error message apprears when stored
configuration is corrupted or on versions earlier than 0.8.2.3 when you're
using Lemonldap::NG with different server types (32 and 64 bits for
example). In this case, you've to upgrade your Lemonldap::NG to at least
0.8.2.3.
<h4 class="heading-1-1-1"><span id=
"H22Configurationisinoldformat2Cyou27vetomigrate2122">"Configuration is in
old format, you've to migrate !"</span></h4>
<p class="paragraph"></p>This warning message means that you are using a
configuration generated by an earlier version than 0.8.2.3 with a more
up-to-date Lemonldap::NG component. You just have to re-save configuration
with a recent manager to avoid this warning.
<h4 class="heading-1-1-1"><span id=
"H22My3A3APackage3Agetconfiguration122">"My::Package: get configuration
1"</span></h4>
<p class="paragraph"></p>Information message: an Apache child process load
configuration.
<h4 class="heading-1-1-1"><span id=
"H22My3A3APackage3Astoreconfiguration122">"My::Package: store
configuration 1"</span></h4>
<p class="paragraph"></p>Information message: an Apache child process
stores the last configuration in the local cache. It will be read by other
Apache childs before 10 minutes.
<h4 class="heading-1-1-1"><span id=
"H22My3A3APackage3ANocookiefound22">"My::Package: No cookie
found"</span></h4>
<p class="paragraph"></p>Information message: one non-authenticated user
tries to connect to the protected application.
<h4 class="heading-1-1-1"><span id=
"H22Redirect26lt3Bxxxx26gt3Btoportal28urlwas2F2922">"Redirect
&lt;x.x.x.x&gt; to portal (url was /)"</span></h4>
<p class="paragraph"></p>Debug message: the client x.x.x.x is redirected
to the authentication portal.
<h4 class="heading-1-1-1"><span id="H22FoundaCDAidRedirecting22">"Found a
CDA id. Redirecting"</span></h4>
<p class="paragraph"></p>Debug message: the client has been authenticated
in another domain (CDA mechanism). The handler generates the cookie in the
new domain.
<h4 class="heading-1-1-1"><span id=
"H22Usersomeonewasauthorizatedtoaccessto2F22">"User someone was
authorizated to access to /"</span></h4>
<p class="paragraph"></p>Debug message: the user "someone" has been
authorizated to access to this URL.
<h4 class="heading-1-1-1"><span id=
"H22My3A3APackage3Aremovingcookie22">"My::Package: removing
cookie"</span></h4>
<p class="paragraph"></p>Debug message: after grant, the handler removes
hides the cookie. Protected application needs only headers.
<h4 class="heading-1-1-1"><span id=
"H22ErrorwhilereadingconfigurationwithglobalStorageOptionskey3A22">"Error
while reading configuration with globalStorageOptions key:"</span></h4>
<p class="paragraph"></p>Configuration is corrupted. See the following
error.
<h4 class="heading-1-1-1"><span id=
"H22UserrejectedbecauseVirtualHosttestexamplecomhasnoconfiguration22">"User
rejected because VirtualHost test.example.com has no
configuration"</span></h4>
<p class="paragraph"></p>When a virtual host is protected but not
configured, Lemonldap::NG block it. Update your configuration to add this
new virtual host, save and apply it.
<h4 class="heading-1-1-1"><span id=
"H22Thecookiexxxxisn27tyetavailable3AObjectdoesnotexistinthedatastoreat2Fusr2Fshare2Fperl52FApache2FSession2FStore2FFilepmline9026231103B22">
"The cookie xxxx isn't yet available: Object does not exist in the data
store at /usr/share/perl5/Apache/Session/Store/File.pm line
90.n"</span></h4>
<p class="paragraph"></p>This message appears when a user use an old
cookie that has been deleted from session database. He has to
re-authenticated itself.
<h4 class="heading-1-1-1"><span id=
"H22Thecookiexxxxisn27tyetavailable3A7E7E26lt3BApache3A3ASessionerrormessage26gt3B7E7E">
"The cookie xxxx isn't yet available: <i class=
"italic">&lt;Apache::Session error message&gt;</i></span></h4>
<p class="paragraph"></p>This message appears when an handler can not
access to session database. The real error is reported.
</div>
</body>
</html>