## @file # Help messages used by the manager. ## @class # Import help messages subroutines in Lemonldap::NG::Manager in the wanted language. package Lemonldap::NG::Manager::Help; use AutoLoader qw(AUTOLOAD); our $VERSION = '0.5'; ## @fn void import(string lang) # Import help messages subroutines in Lemonldap::NG::Manager in the wanted language. # @param $lang language, or $ENV{HTTP_ACCEPT_LANGUAGE} by default # @return nothing sub import { my ($caller_package) = caller; my $lang = shift || $ENV{HTTP_ACCEPT_LANGUAGE}; $lang = lc($lang); foreach ( split( /[,;]/, $lang ) ) { next if /=/; s/fr-fr/fr/; s/en-us/en/; if ( __PACKAGE__->can("help_groups_$_") ) { $l = $_; last; } } $l ||= "en"; foreach $h ( qw(authParams cookieName domain groups ldap macros storage timeout vars whatToTrace virtualHosts portalForceAuthn default samlIDPMetaDataNode samlServicePrivateKey) ) { *{"${caller_package}::help_$h"} = \&{"help_${h}_$l"}; } } 1; __END__ =pod =cut sub help_authParams_en { print <Authentication Parameters
Authentication type
By default,Lemonldap::NG uses ldap authentication scheme using user password. You can change :
  • "SSL" : authentication is done by Apache and the portal checks if SSL variables are set (mail by default),
  • "Apache" : authentication is done by Apache with any mechanism that set REMOTE_USER environment variabme. this permits to use any Apache authentication module as Basic, Kerberos, Pam,...
  • "CAS" : authentication is done using CAS library.
Portal
Set here the URL used to authenticate users (portal). The portal has to inherits from Lemonldap::NG::Portal::SharedConf.
Secured cookie (SSL)
An authenticated user is known by his cookie. If all (virtual) hosts use HTTPS, set this value to 1 so the cookie will be protected and will not be transmitted unless https is used. You can also set it to generate 2 cookies, 1 secure and the other not. Handlers detects if they are in https mode or not and will choose the good cookie.
EOT } sub help_authParams_fr { print <Paramètres d'authentification
Type d'authentification
Le schéma classique d'authentification Lemonldap::NG consiste à utiliser une authentification par vérification de mot de passe sur un annuaire LDAP. Vous pouvez changer ceci en 
  • "SSL" : l'authentification est confiée à Apache et le portail vérifie les variables SSL (mail par défaut),
  • "Apache" : l'authentication est confiée à Apache par un mécanisme quelconque renseignant la variable d'environnement REMOTE_USER. Ce mécanise permet d'utiliser tous les modules d'authentification d'Apache tels Basic, Kerberos, Pam,...
  • "CAS" : l'authentification est déléguée à la librairie CAS.
Portail
Indiquez ici l'URL ou seront renvoyés les utilisateurs non authentifiés. Cette URL doit bien sur correspondre à un portail utilisant Lemonldap::NG::Portal::SharedConf.
Cookie sécurisé (SSL)
Une fois authentifié, l'utilisateur est reconnu par son cookie. Si tous les hôtes virtuels de votre domaine son protégés par SSL, mettez cette option à 1, ainsi le cookie ne sera présenté par le navigateur qu'aux sites protégés, ce qui évite un vol de session. Vous pouvez également mettre cette valeur à 2 pour générer 2 cookies, l'un sécurisé et l'autre non. Les agents (handlers) détectent automatiquement s'il sont en mode https ou non et choisissent le bon cookie.
EOT } sub help_cookieName_en { print <Cookie Name

Set here the name of the cookie ('lemonldap' by default).
WARNING, any change here needs to restart all the Apache servers that use a Lemonldap::NG::Handler.

EOT } sub help_cookieName_fr { print <Nom de cookie

Indiquez ici le nom du cookie ('lemonldap' par défaut).
ATTENTION, tout changement nécessite le redémarrage de tous les serveurs Apache hébergeant des agents de protection Lemonldap::NG::Handler.

EOT } sub help_domain_en { print <Protected domain

Set here the main domain (or sub-domain) protected by Lemonldap::NG. If you use "Cross domain authentication", set here the domain of the portal.
WARNING : all the virtual hosts that are not under the same domain than the portal must be protected by handlers that inherits from Lemonldap::NG::Handler::CDA and if such handlers exist, you have to use Lemonldap::NG::Portal::CDA. EOT } sub help_domain_fr { print <Domaine protégé

Indiquez ici le nom du domaine (ou du sous-domaine) contenant vos applications à protéger. Si vous utilisez le "Cross domain authentication", indiquez ici le domaine du portail
ATTENTION : tous les hôtes virtuels protégés ne se trouvant pas dans le même domaine que le portail doivent être protégés par un agent héritant de Lemonldap::NG::Handler::CDA et si un seul de ces agents est utilisé, le portail doit être de type Lemonldap::NG::Portal::CDA. EOT } sub help_groups_en { print <User Groups

Groups are not required but accelerate the treatment of the requests. For example, if a virtual host is granted only for 3 users, the rule is :

    # test.example.com - Rules
    default => \$uid eq "user1" or \$uid eq "user2" or \$uid eq "user3"

The problem is that this rule is calculated for each HTTP request. Other example, if 2 sites have the same rules, any modification on one has to be write in the second. The 'groups' system solve this : groups are evaluated one time in the authentication phase, and the result is stored in the \$groups variable. The rule abode becomes :

    # Group declaration
    group1 => \$uid eq "user1" or \$uid eq "user2" or \$uid eq "user3"

    # Use of the group :
    # test.example.com - Rules
    default => \$groups =~ /\\bgroup1\\b/

The last rule is a Perl regular expression (PCRE) that means 'search the word "group1" in the string "groups"'.

The \$groups string joins all the groups where the user matchs the expression. The groups are separated by a space in the \$groups string.

EOT } sub help_groups_fr { print <Groupes d'utilisateurs

Les groupes ne sont pas indispensables mais accélèrent le traitement des requêtes. Par exemple, si un hôte virtuel est autorisé nominativement à user, user2 et user3, la règle d'accès s'écrira :

    # test.example.com - Règles
    default => \$uid eq "user1" or \$uid eq "user2" or \$uid eq "user3"

Le problème est que cette expression sera calculée à chaque requête HTTP. D'autre part, si 2 hôtes virtuels ont la même règle d'accès, toute modification doit être répercutée sur les deux hôtes virtuels. Le système des groupes permet de résoudre ces deux problèmes : lors de la connexion au portail, les expressions complexes sont calculées une fois pour toute la session et le résultat est stocké dans la chaîne \$groups. L'exemple précédent devient alors :

    # Déclaration d'un groupe
    group1 => \$uid eq "user1" or \$uid eq "user2" or \$uid eq "user3"

    # Utilisation :
    # test.example.com - Règles
    default => \$groups =~ /\\bgroup1\\b/

Cette dernière expression est une expression régulière Perl (PCRE) qui correspond à la recherche du mot group1 dans la chaîne \$groups (\\b signifie début ou fin de mot).

La variable exportée \$groups est une chaîne de caractères composés de tous les noms de groupes auquels l'utilisateur connecté appartient (c'est à dire les noms de groupe pour lesquels l'expression est vraie).

EOT } sub help_ldap_en { print <LDAP Parameters

LDAP parameters are used to identify users. They must be set even if authentication is done by another system (SSL for example).

  • LDAP base : required (except if your server accepts the requests without base). Example : 
       dc=example, dc=com
  • LDAP server port : 389 by default ;
  • LDAP server : Name(s) (or IP address(es)) of the LDAP server(s). You can specify more than one server separated by commas and/or spaces, they will be tried in the specified order. You can also use encrypted connections :
    • LDAPS : instead of a server name, use : 
         ldaps://server/
      and don't forget to change port (636 for example).
    • TLS : instead of a server name, use : 
         ldap+tls://server/
      you can also set any of the parameters needed by Net::LDAP start_tls function : 
         ldap+tls://server/?verify=none&capath=/etc/ssl
      See Net::LDAP(3) manual page to know all available parameters. You can also set caPath or caFile parameters in the new() function when building the portal (because they should depend on local file system).
  • LDAP account : optional, must be set if anonymous connection cannot access to the wanted LDAP attributes. This account is used before LDAP authentication to find user's dn ;
  • LDAP password : password corresponding to the account above.
EOT } sub help_ldap_fr { print <Paramètres LDAP

Les paramètres LDAP servent à identifier les utilisateurs. Ils doivent être renseignés même si l'authentification est réalisée par un autre moyen (SSL par exemple).

  • Base de recherche LDAP : obligatoire (à moins que votre serveur LDAP accepte les requêtes sans base). Exemple : 
       dc=example, dc=com
  • Port du serveur LDAP : 389 par défaut ;
  • Serveur LDAP : Nom(s) (ou adresse(s) IP) du(des) serveur(s) LDAP. Vous pouvez indiquer plusieurs serveurs ici séparés par des virgules et/ou des espaces. Ils seront testés dans l'ordre indiqué. Vous pouvez également utiliser des connexions chiffrées :
    • LDAPS : au lieu de noms de serveurs, indiquez ici : 
         ldaps://serveur/
      et n'oubliez pas de changer le port (636 en général).
    • TLS : au lieu de noms de serveurs, indiquez ici : 
         ldap+tls://serveur/
      vous pouvez également y ajouter tous les paramètres demandés par la fonction start_tls de Net::LDAP : 
         ldap+tls://serveur/?verify=none&capath=/etc/ssl
      Reportez-vous à la page de manuel de Net::LDAP(3) pour connaître les paramètres disponibles. Vous pouvez également utiliser les paramètres caPath ou caFile lors de la construction du portail dans la fonction new() (car ils peuvent dépendre du système de fichier local).
  • Compte de connexion LDAP : optionnel, à renseigner si les attributs LDAP utilisés ne sont pas accessibles par une session anonyme. Ce compte est utilisé avant l'authentification pour trouver le dn de l'utilisateur ;
  • Mot de passe LDAP : mot de passe correspondant au compte ci-dessus.
EOT } sub help_macros_en { print <Macros

Macros are used to add new variables to user variables attributes). Those new variables are calculated from other variables issued from LDAP attributes. They can be used anywhere and are seen as LDAP attributes. This mechanism avoid to do more than one time the same operation in the authentication phase. Example :

    # macros
    long_name => \$givenname . " " . \$surname
    admin     => \$uid eq "foo" or \$uid eq "bar"
    
    # test.example.com - Headers
    Name      => \$long_name
    
    # test.example.com - Rules
    ^/admin/ => \$admin

Tips

Redefining LDAP attributes

You can create a macro with the same name than an exported value. If so, the attribute is redefined. Example :

    uid => $uid . "\\\@domain.com"
Using regexp

Suppose you want to extract the string 'admin' or 'user' in an attribute, in Perl, you can use \$mail =~ s/^.*(user|admin)/\$1/. To use it in Lemonldap::NG, you have to do the following :

    mail => (\$mail =~ /(user|admin)/)[0]

Explanation : '\$mail =~ /(user|admin)/' returns 0 or 1, but '(\$mail =~ /(user|admin)/)' is a "list context" so it returns an array containing all elements recognized. So '(\$mail =~ /(user|admin)/)[0]' returns the first element.

EOT } sub help_macros_fr { print <Macros

Les macros permettent d'ajouter des variables calculées à partir des attributs LDAP (variables exportées). Elles sont ensuite vues comme des attributs LDAP. Elles évitent de répéter le même calcul plusieurs fois dans la phase d'authentification. Exemple :

    # macros
    nom_complet => \$givenname . " " . \$surname
    admin => \$uid eq "foo" or \$uid eq "bar"
    
    # test.example.com - En-têtes
    Nom => \$nom_complet
    
    # test.example.com - Règles
    ^/admin/ => \$admin

Astuces

Redéfinir les attributs LDAP

Une macro peut porter le même nom You can create a macro with the same name than an exported value. If so, the attribute is redefined. Example :

    uid => $uid . "\\\@domain.com"
Using regexp

Suppose you want to extract the string 'admin' or 'user' in an attribute, in Perl, you can use \$mail =~ s/^.*(user|admin)/\$1/. To use it in Lemonldap::NG, you have to do the following :

    mail => (\$mail =~ /(user|admin)/)[0]

Explanation : '\$mail =~ /(user|admin)/' returns 0 or 1, but '(\$mail =~ /(user|admin)/)' is a "list context" so it returns an array containing all elements recognized. So '(\$mail =~ /(user|admin)/)[0]' returns the first element.

EOT } sub help_storage_en { print <Sessions Storage

Lemonldap::NG sessions storage works with modules that inherits from Apache::Session. You have to set here the choosen module and add the corresponding parameters :

Examples :

  • Module => Apache::Session::File,
    options :
    • Directory => /var/lib/lemonldap-ng/sessions
  • Module => Apache::Session::MySQL,
    options :
    • DataSource => DBI:mysql:database=lemon;host=1.2.3.4
    • UserName => Lemonldap
    • Password => mypass
    • timeout => 7200

Note : if you use purgeCentralCache script provided in the portal sources (to use in crontab), you can set the timeout parameter to manage sessions end (7200 secondes by default).

EOT } sub help_storage_fr { print <Stockage des sessions

Le stockage des sessions Lemonldap::NG est réalisé au travers des modules hérités de Apache::Session. Vous devez indiquer ici le module choisi et indiquer les paramètres correspondants à ce module :

Exemples :

  • Module => Apache::Session::File,
    options :
    • Directory => /var/lib/lemonldap-ng/sessions
  • Module => Apache::Session::MySQL,
    options :
    • DataSource => DBI:mysql:database=lemon;host=1.2.3.4
    • UserName => Lemonldap
    • Password => mypass
    • timeout => 7200

Note : si vous utilisez le script purgeCentralCache fourni dans les sources du portail (à mettre en crontab), vous pouvez ajouter le paramètre timeout pour gérer la destruction des sessions (7200 secondes par défaut).

EOT } sub help_timeout_en { print <Sessions timeout

Set here the sessions timeout in seconds. It will be used by the purgeCentralStorage script given in the source tree. EOT } sub help_timeout_fr { print <Durée de vie des sessions

Indiquez ici la durée de vie des sessions en secondes. Elle est utilisée par le script purgeCentralStorage fourni dans les sources. EOT } sub help_vars_en { print <Variables (LDAP attributes)

Set here the LDAP attributes you need in your configuration or in exported headers.

Declare as the following :

  <MyName> => <real LDAP attribute name>

Examples :

  uid   => uid
  unit  => ou
Declared names can be used in rules, groups, macros and HTTP headers by using them with '\$'. Example : 
  group1 => \$uid eq 'user1' or \$uid eq 'user2'
EOT } sub help_vars_fr { print <Variables (attributs LDAP)

Indiquez ici tous les attributs LDAP dont vous avez besoin dans votre configuration (pour définir les groupes, les macros, les règles d'accès aux hôtes virtuels ou encore les en-têtes HTTP).

La déclaration d'une variable se fait sous la forme :

  <nom declare> => <nom de l'attribut LDAP>

Exemples :

  uid  => uid
  unite  => ou
Les noms déclarés s'utilisent ensuite dans les règles, les groupes, les macros ou les en-têtes HTTP en les faisant précéder du signe '\$'. Exemple : 
  group1 => \$uid eq 'user1' or \$uid eq 'user2'
EOT } sub help_virtualHosts_en { print <Virtual Hosts

A virtual host configuration is cutted in 2 pieces : the rules and the HTTP headers.

Note : If portal and handlers are not in the same domain than declared in "General Parameters" menu, you have to use CDA modules. Else, session cookie is not seen by handlers.

Rules

A rule associates a regular expression with a perl boolean expression. When a user tries to access to an URL that match with the regular expression, access is granted or not depending on the boolean expression result :

  # Virtual host test.example.com - rules
  ^/protected => \$groups =~ /\\bgroup1\\b/

This rule means that all URL starting with '/protected', are reserved to users member of 'group1'. You can also use 'accept' and 'deny' keywords. 'accept' keyword means that all authenticated users are granted.

If URL doesn't match any regular expression, 'default' rule is called to grant or not.

Logout
You can also write Logout rules to intercept application logout url using the reserved words :
  • logout_sso URL : the request generates a redirection to the portal to call logout mechanism. The request is not given to the application so its logout function is not called. After logout, the user is redirected to the URL,
  • logout_app URL (Apache-2.x only) : the request is transmitted to the application, but the result is not displayed : the user is redirected to the URL,
  • logout_app_sso URL (Apache-2.x only) : the request is transmitted to the application and then, the user is redirected to the portal with the logout call and then, he is redirected to the given URL.

Headers

Headers are used to inform the remote application on the connected user. They are declared as : <Header Name> => <Perl expression>.

Examples :

  Auth-User => \$uid
  Unite     => \$departmentUID
EOT } sub help_virtualHosts_fr { print <Hôtes virtuels

La configuration d'un hôte virtuel est divisée en 2 parties : les règles et les en-têtes HTTP exportés.

Note : pour que le mécanisme d'authentification fonctionne, tous les hôtes virtuels et le portail doivent se trouver dans le domaine déclaré dans les paramètres généraux ou utiliser les modules CDA (Cross-Domain-Authentication) qui gère la transmission de l'identifiant.

Règles

Une règle associe une expression régulière perl à une expression booléenne. Lors de l'accès d'un utilisateur, si l'URL demandée correspond à la règle, le droit d'accès est calculé par l'expression booléenne. Exemple :

  # Hôte virtuel test.example.com - règles
  ^/protected => \$groups =~ /\\bgroup1\\b/

La règle ci-dessus signifie que pour les URL commençant par '/protected', les utilisateurs doivent appartenir au groupe 'group1'. Vous pouvez également utiliser les mots-clefs 'accept' et 'deny'. Attention, 'accept' signifie que tous les utilisateurs authentifiés peuvent accéder.

Si l'URL demandée ne correspond à aucune des expressions régulières, le droit d'accès est calculé à partir de l'expression booléenne définie dans la règle par défaut (default).

Logout
Vous pouvez également écrire des règles pour intercepter les URL de déconnexions des applications en utilisant les mots-clefs :
  • logout_sso URL : la requête entraine une redirection vers le portail avec l'appel au système de déloguage. La requête n'est pas transmise à l'applicationthe. Après déloguage, l'utilisateur est renvoyé vers l'URL,
  • logout_app URL (Apache-2.x seulement) : la requête est transmise à l'applications mais le résultat n'est pas affiché : l'utilisateur est redirigé vers l'URL,
  • logout_app_sso URL (Apache-2.x seulement) : la requête est transmise à l'application et ensuite, l'utilisateur est redirigé vers le portail avec appel au système de déloguage. Il est ensuite redirigé vers l'URL.

En-têtes

Les en-têtes servant à l'application à savoir qui est connecté se déclarent comme suit : <nom de l'en-tête> => <expression Perl>.

Exemples :

  Auth-User => \$uid
  Unite     => \$departmentUID
EOT } sub help_whatToTrace_en { print <What to log in Apache

Set here le name of the variable (attribute) or macro that has to be used in proected application Apache logs (don't forget "\$"). By default : \$uid

EOT } sub help_whatToTrace_fr { print <Donnée à journaliser dans Apache

Indiquez ici le nom de la variable (attribut) ou de la macro qui doit être utilisée pour alimenter les journaux Apache des applications protégées (n'oubliez pas le "\$"). Par défaut : \$uid

EOT } ## portalForceAuthn # en sub help_portalForceAuthn_en { print <Force authentication on portal

By default, once user is authenticated on portal, when he comes back to it, the authentication is kept and the menu is displayed.

Enabling this option will force the user to reauthenticate, and its session will be updated.

ID and start date of the session are not modified. The update date is added in field updateDate.Other informations are updated.

Default value: 0

EOT } #fr sub help_portalForceAuthn_fr { print <Forcer l'authentification sur le portail

Par défaut, lorsqu'un utilisateur est authentifié sur le portail, lorsqu'il y revient son authentification est conservée et le menu est affiché.

L'activation de cette option forcera l'utilisateur à s'authentifier de nouveau et sa session sera alors mise à jour.

L'identifiant et la date de création de la session ne sont pas modifiés. La date de mise à jour est indiquée dans le champ updateDate. Les autres informations son mises à jour.

Valeur par défaut : 0

EOT } ## default # en sub help_default_en { print <Welcome on configuration manager

Parameters are listed in the configuration tree under different categories:

  • General parameters
  • Variables
  • Virtual hosts

Select a category to display parameters and sub categories.

Click on Save button to register modifications.

This interface concerns the global configuration. All parameters can be overriden in the local configuration file named lemonldap-ng.ini.

EOT } # fr sub help_default_fr { print <Bienvenue sur le gestionnaire de configuration

Les paramètres sont listés dans l'arbre de configuration sous différentes catégories :

  • Paramètres généraux
  • Variables
  • Hôtes virtuels

Chosir une catégorie pour afficher les paramètres et sous catégories.

Cliquer sur le bouton Sauvegarder pour enregistrer les modifications.

Cette interface concerne la configuration globale. Tous les paramètres peuvent être surchargés dans le fichier local de configuration nommé lemonldap-ng.ini.

EOT } ## saml # en sub help_saml_en { print <SAML

LemonLDAP::NG is SAML compliant, and can be used as:

  • SAML Service Provider:
    • authentication => SAML
    • userDB => SAML
  • SAML Identity Provider:
    • issuerDB => SAML

SAML features requires Lasso module.

EOT } # fr sub help_saml_fr { print <SAML

LemonLDAP::NG est compatible SAML, et peut être utilisé en tant que :

  • Fournisseur de service SAML :
    • authentication => SAML
    • userDB => SAML
  • Fournisseur d'identité SAML :
    • issuerDB => SAML

L'activation du SAML nécessite le module Lasso.

EOT } ## samlServicePrivateKey # en sub help_samlServicePrivateKey_en { print <SAML service private key

Paste here the service private key in PEM format, with header and footer.

Example:

-----BEGIN RSA PRIVATE KEY-----
MIIBOgIBAAJBANZ2b5wb43eJRYnln2bfo+neq6ZQYksmFtn3juDB/UklfwVN0XPi
8NBHXFQjfXPeVse6Ztjl+C443jRCkSawVZMCAwEAAQJBALO56WrADG5+waIApwdF
YE575wmnz9f+gaQEzN4adDM5CgKplp5a5HUxinkLSMuYHNW7E8sh27A6wsF8zeiZ
9mECIQD1kno1Y9st1NtGsrK9yXL55oTbXD7cdx1m4c2i+5E+WQIhAN+Rx065mJuh
2nsZ7FESLorDzpdrI0SvuNAUI5+7uG3LAiBRvR28Y65yxOTv1U81aLZCg/443a12
yJcaxZIi68VekQIgUTljUcS4HwLkn4jBhIq4gg21humTvKai3GYUszm+PZUCIDnR
X1EobS0/HFKASpX7GG4VTi9Rbd5jWbM5ZfSlCjLJ
-----END RSA PRIVATE KEY-----

The corresponding public key or certificate must be set inside SAML service metadata.

EOT } # fr sub help_samlServicePrivateKey_fr { print <Clé privée du service SAML

Coller ici la clé privé du service au format PEM, en consevant l'en-tête et le pied.

Exemple :

-----BEGIN RSA PRIVATE KEY-----
MIIBOgIBAAJBANZ2b5wb43eJRYnln2bfo+neq6ZQYksmFtn3juDB/UklfwVN0XPi
8NBHXFQjfXPeVse6Ztjl+C443jRCkSawVZMCAwEAAQJBALO56WrADG5+waIApwdF
YE575wmnz9f+gaQEzN4adDM5CgKplp5a5HUxinkLSMuYHNW7E8sh27A6wsF8zeiZ
9mECIQD1kno1Y9st1NtGsrK9yXL55oTbXD7cdx1m4c2i+5E+WQIhAN+Rx065mJuh
2nsZ7FESLorDzpdrI0SvuNAUI5+7uG3LAiBRvR28Y65yxOTv1U81aLZCg/443a12
yJcaxZIi68VekQIgUTljUcS4HwLkn4jBhIq4gg21humTvKai3GYUszm+PZUCIDnR
X1EobS0/HFKASpX7GG4VTi9Rbd5jWbM5ZfSlCjLJ
-----END RSA PRIVATE KEY-----

La clé publique ou le certificat correspondant doit être défini dans les metadonnées du service.

EOT }