## @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 portal securedCookie) ) { *{"${caller_package}::help_$h"} = \&{"help_${h}_$l"}; } } 1; __END__ =pod =cut ## authParams # en sub help_authParams_en { print <Modules

LemonLDAP::NG use three types of modules:

Authentication module

Users module

Password module

EOT } #fr sub help_authParams_fr { print <Modules

LemonLDAP::NG utilise trois types de modules :

Module d'authentification

Module utilisateurs

Module de mot de passe

EOT } ## portal # en sub help_portal_en { print <Portal

Set here the URL where users go to authenticate.

Default value: http://auth.example.com

This URL must be inside the principal SSO DNS domain

EOT } # fr sub help_portal_fr { print <Portail

Adresse où les utilisateurs viennent s'authentifier.

Valeur par défaut : http://auth.example.com

Cette adresse doit faire partie du domaine DNS principal.

EOT } ## securedCookie # en sub help_securedCookie_en { print <Secured cookie

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.

Default value: 0

EOT } # fr sub help_securedCookie_fr { print <Cookie sécurisé

Un utilisateur authentifié est reconnu par son cookie. Si tous les hôtes (virtuels) utilisent HTTPS, mettez cette valeur à 1 afin que les cookie soit protégé, c'est-à-dire qu'il ne sera envoyé qu'aux applications HTTPS. Il est également possible de générer 2 cookies (un sécurisé, l'autre non). Le Handler détecte alors lequel des deux utiliser.

Valeur par défaut : 0

EOT } ## cookieName # en sub help_cookieName_en { print <Cookie Name

Set here the name of the cookie.

Default value: lemonldap

Any change here needs to restart all the Apache servers that use a Handler.

EOT } # fr sub help_cookieName_fr { print <Nom de cookie

Indiquez ici le nom du cookie.

Valeur par défaut : lemonldap

Tout changement nécessite le redémarrage de tous les serveurs Apache hébergeant un Hanlder.

EOT } ## domain # en sub help_domain_en { print <Protected domain

Set here the main DNS domain (or sub-domain) protected by LemonLDAP::NG.

Default value: example.com

If some protected applications belongs to another domain, you need to activate the cross-domain authentication feature (also called multiple domains).

EOT } # fr sub help_domain_fr { print <Domaine protégé

Indiquez ici le nom du domaine DNS (ou du sous-domaine) contenant vos applications à protéger.

Valeur par défaut : example.com

Si certaines applications protégées appartiennent à un domaine DNS différent, il faut alors activer l'option de domaines croisés (aussi appelée domaines multiples)

EOT } ## groups # en 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 written 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 above 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 matches the expression. The groups are separated by a space in the \$groups string.

EOT } # fr 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 à user1, 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édente 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ée de tous les noms de groupes auxquels l'utilisateur connecté appartient (c'est à dire les noms de groupe pour lesquels l'expression est vraie).

EOT } ## ldap # en sub help_ldap_en { print <LDAP parameters
  • Server host: 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/
    • 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).
  • Server port: only used if no LDAP URI used in Server host
  • Users search base: DN of users branch. Example: 
    dc=example, dc=com
  • 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 DN. It is also used for password modification.
  • Password: password corresponding to the account above.
EOT } # fr sub help_ldap_fr { print <Paramètres LDAP
  • Hôte: 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/
    • 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).
  • Port: utilisé seulement si l'hôte n'est pas une URI LDAP
  • Base de recherche des utilisateurs: DN de la branche des utilisateurs. Exemple : 
    dc=example, dc=com
  • 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. Il est également utilisé pour la modification du mot de passe.
  • Mot de passe LDAP: mot de passe correspondant au compte ci-dessus.
EOT } ## macros # en 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 user attributes. They can be used anywhere and are seen as normal 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 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 regural expressions

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 } # fr sub help_macros_fr { print <Macros

Les macros permettent d'ajouter des variables calculées à partir des attributs de l'utilisateur (variables exportées). Elles sont ensuite vues comme des attributs classiques. 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

Une macro peut porter le même nom qu'un attribut exporté. Si c'est la cas, l'attribut est redéfini. Exemple :

    uid => $uid . "\\\@domain.com"
Utilisation des expressions régulières

En supposant que l'on souhaite extraire la chaîne 'admin' ou 'user' d'un attribut, en Perl, on peut utiliser \$mail =~ s/^.*(user|admin)/\$1/. Pour l'utiliser dans Lemonldap::NG, il faut faire :

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

Explication : \$mail =~ /(user|admin)/ retourne 0 ou 1, mais (\$mail =~ /(user|admin)/) est un contexte de liste donc il retourne un tableau contenant tous les éléments reconnus. Donc (\$mail =~ /(user|admin)/)[0] renvoie le premier élément.

EOT } ## storage # en 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: 
    Directory => /var/lib/lemonldap-ng/sessions
  • Module Apache::Session::MySQL: 
          DataSource => DBI:mysql:database=lemon;host=1.2.3.4
      UserName => Lemonldap
      Password => mypass
EOT } # fr 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 les paramètres correspondants.

Exemples :

  • Module Apache::Session::File: 
     Directory => /var/lib/lemonldap-ng/sessions
  • Module Apache::Session::MySQL: 
          DataSource => DBI:mysql:database=lemon;host=1.2.3.4
      UserName => Lemonldap
      Password => mypass
EOT } ## timeout # en sub help_timeout_en { print <Sessions timeout

Set here the sessions timeout in seconds. It will be used by the purgeCentralStorage script installed in cron directory.

The timeout does not take into account user activity. A timeout of 2 hours will close a session 2 hours after its creation, even if user is still using it.

EOT } # fr 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 installé dans le cron.

La durée de vie ne tient pas compte de l'activité de l'utilisateur. Une durée de vie de 2 heures fermera la session 2 heures après sa création, même si l'utilisateur est toujours en train de l'utiliser.

EOT } ## vars # en sub help_vars_en { print <Exported variables

Set here the attributes that will be collected from userDb

Declare as the following:

MyName => real_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 } # fr sub help_vars_fr { print <Variables exportées

Indiquez ici tous les attributs qui seront collectés depuis userDB

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

  MonNom => nom_reel_attribute

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 } ## virtualHosts # en sub help_virtualHosts_en { print <Virtual Hosts

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

If portal and Handlers are not in the same domain than declared in General Parameters menu, active Cross-Domain Authenticatin functionnality. 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, deny and unprotect keywords

  • accept: all authenticated users are granted,
  • deny: no one is granted,
  • unprotect: authenticaion not required.

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 } # fr 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.

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 alors il faut activer la fonction Cross-Domain-Authentication.

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, deny et unprotect:

  • accept: tous les utilisateurs authentifiés peuvent accéder,
  • deny: personne ne peut accéder,
  • unprotect: l'authentification n'est pas obligatoire.

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

Déconnexion
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 entraîne une redirection vers le portail avec l'appel au système de déconnexion. La requête n'est pas transmise à l'application. Après déconnexion, 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éconnexion. Il est ensuite redirigé vers l'URL.

En-têtes

Les en-têtes permettant à l'application de savoir qui est connecté se déclarent comme suit :

<nom de l'en-tête> => <expression Perl>.

Exemples :

  Auth-User => \$uid
  Unite     => \$departmentUID
EOT } ## whatToTrace # en sub help_whatToTrace_en { print <User name in Apache

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

This value will be pushed in REMOTE_USER environment variable.

Default value: \$uid

EOT } # fr sub help_whatToTrace_fr { print <Nom de l'utilisateur 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 "\$").

Cette valeur sera inscrite dans la variable d'environnement REMOTE_USER.

Valeur 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
  • SAML2 service
  • SAML2 identity providers

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
  • Service SAML2
  • Fournisseurs d'identité SAML2

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

Load here the service private key in PEM format.

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 loaded inside SAML service metadata.

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

Charger ici la clé privé du service au format PEM.

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 chargé dans les metadonnées du service.

EOT }