Reprise en markdown de la doc du dokuwiki

README.md

+# UnicaenAuth
+
+Ce module :
+
+- ajoute à une application la possibilité d'identifier/authentifier l'utilisateur (LDAP, base de données ou CAS).
+- fournit la possibilité à l'utilisateur de se créer un compte dans la base de données de l'application (option de config).
+- fournit les fonctionnalités d'habilitation de l'utilisateur (ACL).
+- Une bibliothèque de rôles éditable via une IHM
+- Un système de gestion des droits avec des privilèges éditables via une IHM
+- Un système d'assertions avancées pour gérer des cas complexes d'autorisations
+- requiert les modules suivants :
+  - UnicaenApp
+  - ZfcUserDoctrineOrm
+  - phpCAS
+  - BjyAuthorize
+
+## Documentation
+
+- [Installation](./doc/installation.md)
+- [Configuration](./doc/configuration.md)
+- [Authentification](./doc/authentification.md)
+- [Services](./doc/services.md)
+- [Utilisation de la gestion des droits et privilèges](./doc/droits.md)
+- [Aides de vue (view helpers)](./doc/helpers.md)

doc/authentification.md

+# Authentification
+
+## Sources d'authentification
+
+Les 3 sources suivantes sont sollicitées successivement jusqu'à ce que l'une d'entre elles valide l'authentification de l'utilisateur.
+
+1/ Annuaire LDAP
+
+- La connexion à l'annuaire LDAP est requise pour authentifier (ldap_bind) et récupérer les infos concernant l'utilisateur (cf. configuration du module UnicaenApp).
+- Il est possible d'enregistrer systématiquement l'utilisateur authentifié dans la base de données de l'application.
+
+2/ Table des utilisateurs
+
+- Il peut arriver qu'une appli ait besoin d'authentifier des personnes n'existant pas dans l'annuaire LDAP.
+- Pour donner accès à l'application à un nouvel utilisateur, 2 solutions :
+  - Un informaticien crée à la main l'utilisateur dans la table des utilisateurs ; le mot de passe doit être chiffré avec “Bcrypt”
+  (exemple en ligne de commande à la racine de votre projet : `php --run 'require "vendor/autoload.php"; $bcrypt = new Zend\Crypt\Password\Bcrypt(); var_dump($bcrypt->create("azerty"));'`).
+  - Si la fonctionnalité est activée (fournie par le module "zf-commons/zfc-user" dont dépend le module UnicaenAuth), l'utilisateur s'enregistre lui-même dans la table des utilisateurs via un formulaire de l'application (le lien figure sous le formulaire de connexion à l'appli).
+
+3/ Serveur CAS
+
+- L'authentification est déléguée au serveur CAS grâce au module jasig/phpcas (bibliothèque phpCAS).
+- NB: La connexion à l'annuaire LDAP est tout de même requise pour récupérer les infos concernant l'utilisateur (cf. configuration du module UnicaenApp).
+
+## Événement UserAuthenticatedEvent
+
+Si vous avez activé l'enregistrement automatique de l'utilisateur authentifié dans la base de données de votre application, la classe abstraite UnicaenAuth\Event\Listener\AuthenticatedUserSavedAbstractListener peut vous intéresser.
+
+Elle vous procure un moyen de “faire quelque chose” juste avant que l'entité utilisateur (fraîchement authentifié via LDAP) ne soit persistée. L'idée est d'écouter un événement particulier déclenché lors du processus d'authentification de l'utilisateur.
+
+*Attention! Cet événement est déclenché par l'authentification LDAP, mais pas par l'authentification à partir d'une table locale en base de données.*
+
+*Si vous avez mis en place (en plus ou à la place de l'authentification LDAP) une authentification à partir d'une table locale, écoutez plutôt l'événement authentication.success déclenché par le module ZfcUser une fois que l'authentification a réussi. Exemple :*
+
+Module.php
+
+    public function onBootstrap(MvcEvent $e) {
+        //...
+        $e->getApplication()->getEventManager()->getSharedManager()->attach(
+            "*",
+            'authenticate.success',
+            array($this, 'onUserLogin'),
+            100
+        );
+    }   
+    //...        
+    public function onUserLogin( $e ) {
+          if (is_string($identity = $e->getIdentity())) {
+             // login de l'utilisateur authentifié
+             $username = $identity;
+             //...
+          } else {
+             // id de l'utilisateur authentifié dans la table
+             $id = $identity;
+             //...
+          }
+          //...
+    }        
+
+Exemple :
+
+UserAuthenticatedEventListener.php
+
+    namespace Application\Auth;
+     
+    use Application\Entity\Db\Role;
+    use Application\Entity\Db\Utilisateur;
+    use UnicaenAuth\Event\Listener\AuthenticatedUserSavedAbstractListener;
+    use UnicaenAuth\Event\UserAuthenticatedEvent;
+    use UnicaenAuth\Service\UserContext as UserContextService;
+     
+    class UserAuthenticatedEventListener extends AuthenticatedUserSavedAbstractListener
+    {
+        /**
+         * @var Role
+         */
+        private $defaultRole;
+     
+        /**
+         * @param Role $defaultRole
+         */
+        public function setDefaultRole(Role $defaultRole)
+        {
+            $this->defaultRole = $defaultRole;
+        }
+     
+        /**
+         * @var UserContextService
+         */
+        private $userContextService;
+     
+        /**
+         * @param UserContextService $userContextService
+         */
+        public function setAuthUserContextService(UserContextService $userContextService)
+        {
+            $this->userContextService = $userContextService;
+        }
+     
+        /**
+         * @param UserAuthenticatedEvent $e
+         */
+        public function onUserAuthenticatedPrePersist(UserAuthenticatedEvent $e)
+        {
+            /** @var Utilisateur $utilisateur */
+            $utilisateur = $e->getDbUser();
+     
+            // Attribue le profil par défaut à l'utilisateur connecté s'il n'en a aucun.
+            if ($utilisateur->getRoles()->count() === 0 && $this->defaultRole) {
+                $role = $this->defaultRole;
+                $utilisateur->addRole($role);
+            }
+     
+            // Le premier rôle trouvé sera celui endossé par l'utilisateur connecté.
+            if ($role = $utilisateur->getRoles()->first()) {
+                $this->userContextService->setNextSelectedIdentityRole($role);
+            }
+        }
+    }
+
+UserAuthenticatedEventListenerFactory.php
+
+    namespace Application\Auth;
+     
+    use Application\Entity\Db\Role;
+    use Doctrine\ORM\EntityManager;
+    use UnicaenAuth\Service\UserContext as UserContextService;
+    use Zend\ServiceManager\ServiceLocatorInterface;
+     
+    class UserAuthenticatedEventListenerFactory
+    {
+        public function __invoke(ServiceLocatorInterface $serviceLocator)
+        {
+            /** @var EntityManager $em */
+            $em = $serviceLocator->get('doctrine.entitymanager.orm_default');
+     
+            /** @var UserContextService $userContextService */
+            $userContextService = $serviceLocator->get('AuthUserContext');
+     
+            /** @var Role $defaultRole */
+            $defaultRole = $em->getRepository(Role::class)->findOneBy(['isDefault' => true]);
+     
+            $listener = new UserAuthenticatedEventListener();
+            $listener->setDefaultRole($defaultRole);
+            $listener->setAuthUserContextService($userContextService);
+     
+            return $listener;
+        }
+    }
+
+Module.php
+
+    namespace Application;
+     
+    use Application\Auth\UserAuthenticatedEventListener;
+    use Zend\Mvc\MvcEvent;
+     
+    class Module
+    {
+        public function onBootstrap(MvcEvent $e)
+        {
+            $application = $e->getApplication();
+            $eventManager = $application->getEventManager();
+     
+            //...
+     
+            /** @var UserAuthenticatedEventListener $listener */
+            $listener = $sm->get('UserAuthenticatedEventListener');
+            $listener->attach($eventManager);
+        }
+        //...
+    }    
+
+module/Application/config/module.config.php
+
+    return array(
+        //...
+        'service_manager' => array(
+            'factories' => array(
+                //...
+                'UserAuthenticatedEventListener' => 'Application\Auth\UserAuthenticatedEventListenerFactory',
+            ),
+            //...
+        ),
+        //...
+    );

doc/configuration.md

+# Configuration
+
+Il s'agit ici d'adapter certaines options de configuration des modules.
+
+## Configuration globale
+
+- Copier/coller/renommer le fichier config/unicaen-auth.global.php.dist du module vers config/autoload/unicaen-auth.global.php de votre projet.
+- Adapter les informations suivantes à votre contexte (sans modifier le nom des clés)…
+
+### Enregistrement automatique dans la base de l'appli de l'utilisateur authentifié via LDAP
+
+Clé 'save_ldap_user_in_database' : flag indiquant si l'utilisateur authentifié avec succès via l'annuaire LDAP doit être enregistré/mis à jour dans la table des utilisateurs de l'appli (fonctionnalité du module ZfcUser).
+
+*NB : Si vous activez cette fonctionnalité, vous devez spécifier dans la configuration locale du module (voir ci-dessous) les infos de connexion à la base de données d'authentification (“orm_auth”), soit spécifier dans la configuration locale d'un module quelconque les infos de connexion à la base de données principale de l'appli (“orm_default”).*
+
+### Création de compte dans la base de l'appli par l'utilisateur lui-même
+
+Clé 'enable_registration' : autorisation de la création d'un compte utilisateur par l'utilisateur lui-même dans la base de données de l'appli.
+
+*NB : Si vous activez cette fonctionnalité, vous devez spécifier dans la configuration locale du module (voir ci-dessous) les infos de connexion à la base de données d'authentification (“orm_auth”), soit spécifier dans la configuration locale d'un module quelconque les infos de connexion à la base de données principale de l'appli (“orm_default”).*
+
+### Système de gestion des privilèges
+
+Le système de gestion des privilèges est activé par défaut. Il peut néanmoins être désactivé si
+
+- il n'est pas utile à votre application
+- si vous implémentez votre propre système de privilèges
+
+La paramètre booléen unicaen-auth/enable_privileges en détermine l'activation.
+
+### Désctivation d'autres parties d'UnicaenAuth
+
+UnicaenAuth possède ses propres fournisseurs de rôles, d'identités (dans la configuration, rubrique respectives identity_provider et role_providers de bjyauthorize, pré-renseignées dans la configuration globale d'UnicaenAuth.
+
+Tout comme le système de gestion des privilèges, il est possible de désactiver tout ou partie de ces systèmes pour les remplacer par les votres si nécessaire. Il suffit pour cela de commenter les lignes correspondantes dans le fichier de configuration global d'UnicaenAuth copié dans votre projet.
+
+### Interface graphique de gestion (IHM)
+
+Le système de gestion des privilèges d'UnicaenAuth est associé à une interface de gestion qui permet de :
+
+- Gérer les rôles (ajout, modification et suppression de rôles) dynamiquement.
+- Gérer l'association des rôles et des privilèges (les privilèges étant gérés directement en base de données car ces derniers sont liés au code source et ne sont pas dynamiques).
+
+Un menu “Droits d'accès” est affiché par défaut dans votre barre de menu principale. Ceci peut bien entendu être modifié selon vos souhaits dans le fichier de configuration global d'UnicaenAuth placé dans votre projet.
+
+## Configuration locale
+
+- Copier/coller/renommer le fichier config/unicaen-auth.local.php.dist du module vers config/autoload/unicaen-auth.local.php de votre projet.
+- Adapter les informations suivantes à votre contexte (sans modifier le nom des clés)…
+
+### Authentification centralisée
+
+Clé 'cas' : décommenter pour activer l'authentification CAS, commenter pour la désactiver, exemple :
+
+unicaen-auth.local.php
+
+        'cas' => array(
+            'connection' => array(
+                'default' => array(
+                    'params' => array(
+                        'hostname' => 'cas.unicaen.fr',
+                        'port' => 443,
+                        'version' => "2.0",
+                        'uri' => "",
+                        'debug' => false,
+                    ),
+                ),
+            ),
+        ),
+
+### Usurpation d'identité
+
+Clé 'usurpation_allowed_usernames' : liste des identifiants de connexion des utilisateurs (issus de l'annuaire LDAP) autorisés à se connecter à l'appli sous l'identité de n'importe quel utilisateur (issus de l'annuaire LDAP ou de la base de données d'authentification), exemple :
+
+unicaen-auth.local.php
+
+        'usurpation_allowed_usernames' => array('gauthierb'),
+
+D'après cet exemple, l'utilisateur “gauthierb” est habilité à saisir dans le formulaire de connexion à l'appli l'identifiant “gauthierb=fernagut” et son mot de passe habituel pour se faire passer pour l'utilisateur “fernagut”.

doc/helpers.md

+# Aides de vue (view helpers)
+
+## AppConnection
+
+Aide de vue générant le lien et les infos concernant la connexion à l'application.
+
+## UserConnection
+
+Aide de vue générant le code HTML du lien de connexion ou de déconnexion à l'appli selon que l'utilisateur est connecté ou non.
+
+## UserCurrent
+
+Aide de vue générant le code HTML d'affichage de toutes les infos concernant l'utilisateur courant, à savoir :
+
+- “Aucun” + lien de connexion OU BIEN nom de l'utilisateur connecté + lien de déconnexion
+- profil de l'utilisateur connecté (ex: standard, gestionnaire, administrateur, etc.)
+- infos administratives sur l'utilisateur (affectation, responsabilité)
+
+## UserInfo
+
+Aide de vue générant le code HTML d'affichage des infos administratives sur l'utilisateur (affectations, responsabilités).
+
+## UserProfile
+
+Aide de vue permettant d'afficher le profil de l'utilisateur connecté.
+
+## UserStatus
+
+Aide de vue de rendu des éléments concernant le statut de connexion à l'appli, à savoir :
+
+- si un utilisateur est connecté : l'identité de l'utilisateur connecté et un lien pointant vers la demande de déconnexion
+- sinon : un lien pointant vers le formulaire de connexion

doc/installation.md

+# Installation
+
+Cette page traite de l'installation du module UnicaenAuth au sein d'une application ne l'utilisant par encore.
+
+## Module
+
+- Éditez le fichier composer.json se trouvant à la racine de votre projet et assurez-vous que le “repository” suivant est bien présent :
+
+composer.json
+
+        "repositories": [
+            { 
+                "type": "composer", 
+                "url": "http://dev.unicaen.fr/packagist" 
+            }
+        ],
+
+- Ajoutez à présent la dépendance suivante :
+
+composer.json
+
+        "require": {
+            ...
+            "unicaen/unicaen-auth": "dev-master"
+        },
+        "minimum-stability": "dev"
+
+- Placez-vous à la racine de votre projet et lancez la commande suivante dans un shell :
+
+$ php ../composer.phar update
+
+La commande ci-dessus fonctionne seulement si le binaire composer.phar se trouve dans le répertoire parent. Plus d'infos : http://getcomposer.org.
+
+- Activez les modules suivants dans cet ordre dans le fichier config/application.config.php de l'application :
+
+    'modules' => array(
+        'Application',
+        'ZfcBase', 'DoctrineModule', 'DoctrineORMModule', 'ZfcUser', 'ZfcUserDoctrineORM', 'BjyAuthorize', 
+        'UnicaenApp', 'AssetManager',
+        'UnicaenAuth',
+        // ...
+    ),
+
+## Base de données
+
+Des tables doivent être créées/initialisées dans une base de données si vous prévoyez d'activer l'une des fonctionnalités suivantes :
+
+- enregistrement / mise à jour de l'utilisateur authentifié dans la table des utilisateurs de l'appli (save_ldap_user_in_database) ;
+- création d'un compte utilisateur par l'utilisateur lui-même (enable_registration) ;
+- attribuer des rôles aux utilisateurs dans la base de données.
+- gestion complète des rôles et privilèges
+
+Voici le script à utiliser :
+
+    vendor/unicaen/unicaen-auth/data/schema.sql
+
+Vous pouvez paramétrer l'accès à la base de données : par défaut 'doctrine.entitymanager.orm_default' est utilisé mais vous pouvez en choisir un autre (dans la config, modifier le paramètre unicaen-auth/entity_manager_name).

doc/services.md

+# Liste des services proposés
+
+Voici la liste des services proposées :
+
+| Nom |	Classe | Description |
+| ----|--------|-------------|
+| UnicaenAuth\Service\Privilege |          UnicaenAuth\Service\PrivilegeService |	       Gère les privilèges (depuis la BDD)
+| UnicaenAuth\Service\CategoriePrivilege | UnicaenAuth\Service\CategoriePrivilegeService | Gère les catégories de privilèges (depuis la BDD)
+| UnicaenAuth\Service\Role |               UnicaenAuth\Service\RoleService |               Gère les rôles (depuis la BDD)
+| UnicaenAuth\Service\UserContext |        UnicaenAuth\Service\UserContext |               Fournit un ensemble de méthodes liés à l'utilisateur
\ No newline at end of file