palladium
Who is that "index" and where to find it
(travail en cours : documentation pour 2.0)
Bibliothèque pour gérer l'identification de l'utilisateur.
Le but de cette bibliothèque est de localiser le compte de l'utilisateur (pour être précis - son identifiant unique) pour une preuve d'identité donnée et de gérer différents types d'identités. Il se compose de 4 services différents : Identification, Enregistrement, Recherche et Récupération.
Vous pouvez ajouter la bibliothèque à votre projet à l'aide de composer avec la commande suivante :
composer require teresko/ palladiumPour utiliser ce package, il nécessite PHP version 7.0+ et PDO.
Vous devrez également créer un tableau dans lequel stocker les identités . L’exemple de schéma est disponible ici. Elle ne contient actuellement que la définition de table pour MySQL/MariaDB, mais la bibliothèque peut être utilisée avec n'importe quel SGBDR doté d'un pilote PDO.
palladium contient 4 services : Registration , Identification , Search et Recovery . Chacun de ces services a deux dépendances obligatoires :
palladium ContractCanPersistIdenity )PsrLogLoggerInterface )Cela vous donne la possibilité de remplacer le référentiel par défaut, si vous souhaitez modifier ou remplacer des parties de la couche d'abstraction de persistance. En ce qui concerne l'enregistreur, l'approche recommandée consiste à utiliser Monolog, mais cela fonctionnerait avec n'importe quel système de journalisation compatible.
Le référentiel par défaut est également doté de fonctionnalités permettant d'ajouter des types d'identité personnalisés et des mappeurs de données, qui sont utilisés pour votre type d'identité ou pour les types d'identité intégrés. Pour plus de détails sur l'utilisation, consultez la section %TODO%.
Dans le constructeur du service Identification , il existe un troisième et un quatrième paramètre facultatif :
Dans le constructeur du service Registration , il existe un troisième paramètre facultatif :
Comme indiqué ci-dessus, les 4 services attendent un référentiel en tant que dépendance du constructeur. Si vous ne remplacez pas le référentiel fourni par votre version personnalisée, vous devrez alors initialiser palladium RepositoryIdentity et le transmettre aux services.
Le référentiel fourni lui-même a une seule dépendance : instance, qui implémente palladium ContractCanCreateMapper . Ce contrat (interface) est implémenté par palladium ComponentMapperFactory . Et cette fabrique a deux dépendances : l'instance PDO et le nom de la table, où les identités seront stockées.
<?php
$ factory = new palladium Component MapperFactory ( new PDO (... $ config ), $ tableName );
$ repository = new palladium Repository Identity ( $ factory ); Dans tous les autres exemples de code, où vous voyez la variable $repository utilisée, vous pouvez supposer qu'elle a été initialisée à l'aide de cet exemple de code.
Pour les utilisateurs du composant DependencyInjection de Symfony (version : 3.4+), il existe un exemple de fichier de configuration : %TODO%
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); Si l'opération est terminée avec succès, la variable $identity contiendra une instance de StandardIdentity non vérifiée. Pour terminer la vérification, vous devrez utiliser le jeton que contient l'identité. Dans l'exemple donné, ce jeton peut être évalué à l'aide de $instance->getToken() .
La méthode createStandardIdentity() peut lever une exception IdentityConflict , si le courrier électronique a déjà utilisé une autre identité.
La méthode createStandardIdentity() possède un troisième paramètre facultatif, qui définit la durée de vie du jeton de vérification de l'e-mail en secondes. Une fois appliqué, l'exemple précédent se présente comme suit :
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' , 3600 );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); Cela rendra le jeton de vérification utilisable pendant 1 heure après l'enregistrement de l'identité de cet utilisateur. Une fois ce délai écoulé, vous ne pourrez plus trouver cette identité à l’aide de findStandardIdentityByToken() dans le service Search .
IMPORTANT : la méthode
createStandardIdentity()ne valide pas l'email des utilisateurs ni tout autre type d'identifiant. Il vérifie uniquement son caractère unique. La validation des e-mails, numéros de téléphone, surnoms et autres identifiants dépasse le cadre de cette bibliothèque.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByToken ( $ token , palladium Entity Identity:: ACTION_VERIFY );
$ registration -> verifyStandardIdentity ( $ identity ); La valeur $token est utilisée pour localiser l' EmailIdentity correspondant, qui est ensuite vérifié. Si l'identité n'est pas trouvée, findStandardIdentityByToken() lèvera l'exception IdentityNotFound .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ cookie = $ identification -> loginWithPassword ( $ identity , $ password ); Si aucune identité correspondante avec l'identifiant donné (comme une adresse e-mail) n'est trouvée, la méthode findStandardIdentityByIdentifier() lèvera une exception IdentityNotFound .
Dans le cas où le mot de passe ne correspond pas, la méthode loginWithPassword() lancera une exception PasswordMismatch .
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId ); Cela créera une nouvelle instance de NonceIdentity . Pour l'utiliser pour la connexion, vous aurez besoin de valeurs dans NonceIdentity::getIdentifier() et NonceIdentity::getKey() , où l'identifiant sera utilisé pour localiser l'identité occasionnelle et la clé sera utilisée pour vérifier.
La méthode createNonceIdentity() était un deuxième paramètre facultatif, qui définit la durée de vie de cette identité à usage unique en secondes. Une fois appliqué, l'exemple précédent se présente comme suit :
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId , 600 ); Cela rendra l’identité à usage unique utilisable pendant 10 minutes après sa création. Une fois le temps imparti écoulé, la transmission de cette identité dans la méthode d' Identification useNonceIdentity() entraînera la levée d'une exception IdentityExpired .
<?php
$ identity = $ this -> search -> findNonceIdentityByIdentifier ( $ identifier );
$ cookie = $ this -> identification -> useNonceIdentity ( $ identity , $ key ); Si aucune identité correspondante avec l'identifiant donné (adresse e-mail, surnom, ect.) n'est trouvée, la méthode findNonceIdentityByIdentifier() lèvera l'exception IdentityNotFound .
Dans le cas où le mot de passe ne correspond pas, la méthode useNonceIdentity() lèvera une exception KeyMismatch .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ cookie = $ identification -> loginWithCookie ( $ identity , $ key ); Si le cookie n'est pas trouvé à l'aide de findCookieIdentity() une exception IdentityNotFound standard sera levée. La cause possible serait soit que le cookie ne soit plus actif (par exemple, l'utilisateur est déconnecté), soit que le cookie n'existe pas du tout.
Dans le cas où le cookie est trop ancien, loginWithCookie() produira une exception IdentityExpired .
Mais la méthode loginWithCookie() peut également produire une exception CompromisedCookie . Voir une exception à cela pourrait indiquer que le cookie a été volé ou que l'utilisateur n'a jamais reçu de nouvelle valeur de cookie.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> blockIdentity ( $ identity );C'est la méthode recommandée pour traiter les cookies suspects, qui pourraient ou non être volés. Ceci n'est pas destiné à déconnecter les utilisateurs .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> logout ( $ identity , $ key );Cette opération marque le cookie comme « rejeté ». La liste des exceptions qui peuvent être produites correspond à celles décrites dans la section Connexion à l'aide de cookies.
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity ); Si aucune identité correspondante avec l'adresse e-mail donnée n'est trouvée, la méthode findStandardIdentityByIdentifier() lèvera une exception IdentityNotFound .
Lorsque markForReset() est appelé, il doit être fourni avec une instance de StandardIdentity , qui a déjà été vérifiée (sinon, elle risque de divulguer les informations privées de l'utilisateur de votre application). Si ce n’est pas le cas, la méthode lancera une exception IdentityNotVerified .
La méthode markForReset() était un deuxième paramètre facultatif, qui définit la durée de vie du jeton de réinitialisation du mot de passe en secondes. Une fois appliqué, l'exemple précédent se présente comme suit :
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity , 7200 ); Cela rendra le jeton de réinitialisation du mot de passe utilisable pendant deux heures après que l'identité de cet utilisateur ait été marquée pour réinitialisation. Une fois le délai imparti expiré, vous ne pourrez plus trouver cette identité à l'aide de findEmailIdentityByToken() dans le service Search .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findEmailIdentityByToken ( $ token , palladium Entity Identity:: ACTION_RESET );
$ recovery -> resetIdentityPassword ( $ identity , ' foobar ' ); Si aucune identité correspondante avec le jeton donné n'est trouvée, la méthode findEmailIdentityByToken() lèvera l'exception IdentityNotFound .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ identification -> changePassword ( $ identity , $ oldPassword , $ newPassword ); Si aucune identité correspondante avec l'adresse e-mail donnée (ou tout autre type d'identifiant) n'est trouvée, la méthode findStandardIdentityByIdentifier() lèvera l'exception IdentityNotFound .
Dans le cas où le mot de passe ne correspond pas, la méthode changePassword() lancera une exception PasswordMismatch .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ factory , $ logger );
$ list = $ search -> findIdentitiesByParentId ( $ identity -> getId ());
$ identification -> discardIdentityCollection ( $ list ); La valeur de retour de findIdentitiesByParentId() renverra IdentityCollection , qui peut être vide.
Comme mentionné précédemment, les services de cette bibliothèque attendent un enregistreur compatible PSR-3 comme dépendance. Il sera utilisé pour enregistrer trois niveaux d'événements :
LogLevel::INFOCe niveau de journalisation est utilisé pour suivre les opérations ordinaires que l'utilisateur effectuerait lors de l'utilisation de votre application de la manière prévue :
LogLevel::NOTICELes journaux avec ce niveau seront enregistrés si l'utilisateur tente une opération infructueuse, ce qui ne devrait pas se produire dans des scénarios d'utilisation corrects :
LogLevel::WARNINGUtilisé uniquement pour enregistrer les cas, lorsque l'utilisateur tente d'utiliser un cookie compromis.
Cette bibliothèque se concentre sur une tâche spécifique. Il n'inclut aucune des fonctionnalités suivantes :
Si vous pensez que cette bibliothèque d'authentification nécessite l'un des éléments répertoriés ci-dessus, alors ce n'est pas la bibliothèque que vous recherchez.
