palladium
Who is that "index" and where to find it
(trabajo en progreso: documentos para 2.0)
Biblioteca para el manejo de la identificación del usuario.
El propósito de esta biblioteca es localizar la cuenta del usuario (para ser precisos, su identificación única) para una prueba de identidad determinada y administrar varios tipos de identidades. Consta de 4 servicios diferentes: Identificación, Registro, Búsqueda y Recuperación.
Puede agregar la biblioteca a su proyecto usando el compositor con el siguiente comando:
composer require teresko/ palladiumPara utilizar este paquete, se requiere PHP versión 7.0+ y PDO.
También necesitarás crear una tabla donde almacenar las identidades . El esquema de ejemplo está disponible aquí. Actualmente solo contiene definiciones de tablas para MySQL/MariaDB, pero la biblioteca se puede usar con cualquier RDBMS que tenga un controlador PDO.
palladium contiene 4 servicios: Registration , Identification , Search y Recovery . Cada uno de estos servicios tiene dos dependencias obligatorias:
palladium ContractCanPersistIdenity )PsrLogLoggerInterface )Esto le brinda la opción de reemplazar el repositorio predeterminado, si desea alterar o reemplazar partes de la capa de abstracción de persistencia. En cuanto al registrador, el método recomendado es utilizar Monolog, pero funcionaría con cualquier sistema de registro compatible.
El repositorio predeterminado también viene con funcionalidad para agregar tipos de identidad personalizados y asignadores de datos, que se utilizan para sus tipos de identidad o para los integrados. Para obtener detalles de uso, consulte la sección %TODO%.
En el constructor del servicio Identification hay un tercer y cuarto parámetro opcional:
En el constructor del servicio Registration existe un tercer parámetro opcional:
Como se señaló anteriormente, los 4 servicios esperan un repositorio como dependencia del constructor. Si no está reemplazando el repositorio incluido con su versión personalizada, deberá inicializar palladium RepositoryIdentity y pasarlo a los servicios.
El repositorio incluido en sí tiene una única dependencia: instancia, que implementa palladium ContractCanCreateMapper . Este contrato (interfaz) lo implementa palladium ComponentMapperFactory . Y esta fábrica tiene dos dependencias: la instancia PDO y el nombre de la tabla donde se almacenarán las identidades .
<?php
$ factory = new palladium Component MapperFactory ( new PDO (... $ config ), $ tableName );
$ repository = new palladium Repository Identity ( $ factory ); En cualquier otro ejemplo de código, donde vea que se usa la variable $repository , puede asumir que se ha inicializado usando este ejemplo de código.
Para los usuarios del componente DependencyInjection de Symfony (versión: 3.4+), hay un archivo de configuración de muestra: %TODO%
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); Si la operación se completa con éxito, la variable $identity contendrá una instancia de StandardIdentity no verificada. Para completar la verificación, deberá utilizar el token que contiene la identidad. En el ejemplo dado, este token se puede evaluar usando $instance->getToken() .
El método createStandardIdentity() puede generar una excepción IdentityConflict , si el correo electrónico ya se ha utilizado para otra identidad.
El método createStandardIdentity() tiene un tercer parámetro opcional, que define la vida útil del token de verificación de correo electrónico en segundos. Cuando se aplica, el ejemplo anterior tiene el siguiente aspecto:
<?php
$ registration = new palladium Service Registration ( $ repository , $ logger );
$ identity = $ registration -> createStandardIdentity ( ' [email protected] ' , ' password ' , 3600 );
$ registration -> bindAccountToIdentity ( $ accountId , $ identity ); Esto hará que el token de verificación se pueda utilizar durante 1 hora después de que se haya registrado la identidad de este usuario. Después de que pase ese tiempo, no podrá encontrar esta identidad utilizando findStandardIdentityByToken() en el servicio Search .
IMPORTANTE : los métodos
createStandardIdentity()no validan el correo electrónico de los usuarios ni ningún otro tipo de identificador. Sólo comprueba su unicidad. La validación de correos electrónicos, números de teléfono, apodos y otros identificadores está fuera del alcance de esta biblioteca.
<?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 ); El valor $token se utiliza para localizar el EmailIdentity coincidente, que luego se verifica. Si no se encuentra la identidad, findStandardIdentityByToken() generará una excepción 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 no se encuentra ninguna identidad coincidente con el identificador dado (como dirección de correo electrónico), el método findStandardIdentityByIdentifier() generará una excepción IdentityNotFound .
En caso de que la contraseña no coincida, el método loginWithPassword() generará una excepción PasswordMismatch .
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId ); Esto creará una nueva instancia de NonceIdentity . Para usarlo para iniciar sesión, necesitará valores en NonceIdentity::getIdentifier() y NonceIdentity::getKey() , donde el identificador se usará para ubicar la identidad nonce y la clave se usará para verificar.
El método createNonceIdentity() era un segundo parámetro opcional, que define la vida útil de esta identidad de un solo uso en segundos. Cuando se aplica, el ejemplo anterior tiene el siguiente aspecto:
<?php
$ identity = $ this -> registration -> createNonceIdentity ( $ accountId , 600 ); Esto hará que la identidad de un solo uso se pueda utilizar durante 10 minutos después de su creación. Una vez transcurrido el tiempo permitido, pasar esta identidad en el método de Identification useNonceIdentity() dará como resultado que se genere la excepción IdentityExpired .
<?php
$ identity = $ this -> search -> findNonceIdentityByIdentifier ( $ identifier );
$ cookie = $ this -> identification -> useNonceIdentity ( $ identity , $ key ); Si no se encuentra ninguna identidad coincidente con el identificador dado (dirección de correo electrónico, apodo, etc.), el método findNonceIdentityByIdentifier() generará una excepción IdentityNotFound .
En caso de que la contraseña no coincida, el método useNonceIdentity() generará una excepción 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 no se encuentra la cookie usando findCookieIdentity() se generará una excepción estándar IdentityNotFound . La posible causa sería que la cookie ya no esté activa (por ejemplo, el usuario cerró la sesión) o que la cookie no exista en absoluto.
En caso de que la cookie sea demasiado antigua, loginWithCookie() producirá una excepción IdentityExpired .
Pero el método loginWithCookie() también puede producir una excepción CompromisedCookie . Ver una excepción para esto podría indicar que la cookie ha sido robada o que el usuario nunca recibió un nuevo valor 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 );Esta es la forma recomendada de tratar con cookies sospechosas, que pueden ser robadas o no. Esto no está destinado a cerrar la sesión de los usuarios .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ repository , $ logger );
$ identity = $ search -> findCookieIdentity ( $ accountId , $ series );
$ identification -> logout ( $ identity , $ key );Esta operación marca la cookie como "descartada". La lista de excepciones que se pueden producir coincide con las descritas en la sección Iniciar sesión mediante 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 no se encuentra ninguna identidad coincidente con la dirección de correo electrónico dada, el método findStandardIdentityByIdentifier() generará una excepción IdentityNotFound .
Cuando se llama markForReset() , se le debe proporcionar una instancia de StandardIdentity que ya haya sido verificada (de lo contrario, existe la posibilidad de que se filtre información privada del usuario desde su aplicación). Si ese no es el caso, el método generará una excepción IdentityNotVerified .
El método markForReset() era un segundo parámetro opcional, que define la vida útil del token de restablecimiento de contraseña en segundos. Cuando se aplica, el ejemplo anterior tiene el siguiente aspecto:
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ recovery = new palladium Service Recovery ( $ repository , $ logger );
$ identity = $ search -> findStandardIdentityByIdentifier ( $ identifier );
$ token = $ recovery -> markForReset ( $ identity , 7200 ); Esto hará que el token de restablecimiento de contraseña se pueda utilizar durante dos horas después de que la identidad de este usuario haya sido marcada para restablecerse. Cuando el tiempo permitido haya expirado, no podrá encontrar esta identidad utilizando findEmailIdentityByToken() en el servicio 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 no se encuentra ninguna identidad coincidente con el token dado, el método findEmailIdentityByToken() generará una excepción 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 no se encuentra ninguna identidad que coincida con la dirección de correo electrónico dada (o cualquier otro tipo de identificador), el método findStandardIdentityByIdentifier() generará una excepción IdentityNotFound .
En caso de que la contraseña no coincida, el método changePassword() generará una excepción PasswordMismatch .
<?php
$ search = new palladium Service Search ( $ repository , $ logger );
$ identification = new palladium Service Identification ( $ factory , $ logger );
$ list = $ search -> findIdentitiesByParentId ( $ identity -> getId ());
$ identification -> discardIdentityCollection ( $ list ); El valor de retorno de findIdentitiesByParentId() devolverá IdentityCollection , que puede estar vacío.
Como se mencionó anteriormente, los servicios de esta biblioteca esperan un registrador compatible con PSR-3 como dependencia. Se utilizará para registrar tres niveles de eventos:
LogLevel::INFOEste nivel de registro se utiliza para rastrear operaciones ordinarias que el usuario realizaría al usar su aplicación de la manera prevista:
LogLevel::NOTICESe registrarán registros con este nivel si el usuario intenta realizar una operación fallida, lo que no debería ocurrir en escenarios de uso correctos:
LogLevel::WARNINGSolo se utiliza para registrar casos, cuando el usuario intenta utilizar una cookie comprometida.
Esta biblioteca se centra en una tarea específica. No incluye ninguna de las siguientes funciones:
Si cree que esa biblioteca de autenticación requiere una de las partes enumeradas anteriormente, entonces esta no es la biblioteca que está buscando.
