Reprise en markdown de la doc du dokuwiki (b6c99b8f) · Commits · Christophe Turbout / auth

README.md

0 → 100644

+24 −0

Original line number	Diff line number	Diff line
		# 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

0 → 100644

+186 −0

Original line number	Diff line number	Diff line
		# 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

0 → 100644

+79 −0

Original line number	Diff line number	Diff line
		# 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/droits.md

0 → 100644

+537 −0

File added.

Preview size limit exceeded, changes collapsed.

doc/helpers.md

0 → 100644

+32 −0

Original line number	Diff line number	Diff line
		# 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