Lemonldap::NG Frequently Asked Questions

General questions

What is a Web-SSO ?

A SSO (Single Sign On) 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.

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.

What brings Lemonldap::NG compared to the other Web-SSO ?

Configuration

What type of configuration storage has to be used ?

Lemonldap::NG provides 3 configuration storage systems:

The provided example works with HTTP, but not with HTTPS.

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 https parameter. This parameter has to be configured directly in the handlers is not accessible by the manager interface:

__PACKAGE__->init ( {
    localStorage        => "Cache::FileCache",
    localStorageOptions => {
              'namespace'          => 'MyNamespace',
              'default_expires_in' => 600,
              'directory_umask'    => '007',
              'cache_root'         => '/tmp',
              'cache_depth'        => 5,
    },
    configStorage       => {
              type                 => 'File',
              dirName              => '/var/lib/lemonldap-ng/conf',
    },
    https               => 1,
} );

For what is used the "https" parameter ?

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.

What is an auto-protected CGI ?

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:

  use Lemonldap::NG::Handler::CGI;
  my $cgi = Lemonldap::NG::Handler::CGI->new ( {
      # same parameters than a Lemonldap::NG::Handler::SharedConf handler
    }
  );
  $cgi->authenticate;

In the example above, $cgi is a CGI(3) object. The only difference is that it has some additional functions: 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.

How to use Lemonldap::NG with Active-Directory ?

Active-Directory uses cn field instead of uid as unique identifier. You have so to modify Lemonldap::NG configuration in 2 points :
  1. the field cn (or samAccountName) has to be used to find the user in the portal,
  2. Apache has to use this field in logs.
For the second point, you have to replace $uid by $cn in the field "General Parameters -> 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 :

#!/usr/bin/perl
use Lemonldap::NG::Portal::SharedConf;
my $portal = Lemonldap::NG::Portal::SharedConf->new(
    {
        configStorage => {
            type    => 'File',
            dirName => '/var/lib/lemonldap-ng/conf',
        },
        formateFilter => sub {
            my $self = shift;
            $self->{filter} = "(&(cn=" . $self->{user} . ")(objectClass=person))";
            PE_OK;
        } # end of overload
    }
);

How to use Lemonldap::NG as reverse-proxy ?

Lemonldap::NG protects Apache VirtualHosts. To use it as reverse-proxy, you just have to configure Apache as reverse-proxy :

# httpd.conf
<VirtualHost *>
  ServerName MyApplication.com
  PerlRequire MyFile
  PerlHeaderParserHandler My::Package
  ProxyPass / http://real-server/
  ProxyPassReverse / http://real-server/
  # You can also use mod_rewrite instead of mod_proxy
  # RewriteEngine On
  # RewriteRule /(.*)$ http://serveur-reel/$1 [P]
</VirtualHost>

If you prefer to use a Perl proxy, Lemonldap::NG provides one (Lemonldap::NG::Handler::Proxy(3))

Operation

With what serves the handler local cache ?

The handler local cache is used for 2 things :

Why handlers local cache can not be configured by the manager ?

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.

What is the Cross Domain Authentication (CDA) ?

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.

How works the Cross Domain Authentication (CDA) ?

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.

Authentication

How to change authentication scheme ?

Lemonldap::NG provides several authentication modes (to use in the "authentification" field of the administration interface) :

Error and debug messages

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.

"Incorrect XML"

This messages appears when the manager cannot load configuration. The real error can be found in Apache logs.

"Byte order is not compatible" ou "Magic number checking on storable string failed"

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.

"Configuration is in old format, you've to migrate !"

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.

"My::Package: get configuration 1"

Information message: an Apache child process load configuration.

"My::Package: store configuration 1"

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.

"My::Package: No cookie found"

Information message: one non-authenticated user tries to connect to the protected application.

"Redirect <x.x.x.x> to portal (url was /)"

Debug message: the client x.x.x.x is redirected to the authentication portal.

"Found a CDA id. Redirecting"

Debug message: the client has been authenticated in another domain (CDA mechanism). The handler generates the cookie in the new domain.

"User someone was authorizated to access to /"

Debug message: the user "someone" has been authorizated to access to this URL.

"My::Package: removing cookie"

Debug message: after grant, the handler removes hides the cookie. Protected application needs only headers.

"Error while reading configuration with globalStorageOptions key:"

Configuration is corrupted. See the following error.

"User rejected because VirtualHost test.example.com has no configuration"

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.

"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"

This message appears when a user use an old cookie that has been deleted from session database. He has to re-authenticated itself.

"The cookie xxxx isn't yet available: <Apache::Session error message>

This message appears when an handler can not access to session database. The real error is reported.