Palladium

(work-in-progress: docs for 2.0)

Library for handling the user identification.

The purpose of this library is to locate user's account (to be precise - its unique id) for a given proof of identity and to manage various types of identities. It consists of 4 different services: Identification, Registration, Search and Recovery.

Installation

You can add the library to your project using composer with following command:

composer require teresko/palladium

To use this package, it require PHP version 7.0+ and PDO.

You will also need to create a table, where to store the identities. The example schema is available here. It currently contains only table definition for MySQL/MariaDB, but the library can be used with any RDBMS, that has a PDO driver.

Initialization

Palladium contains 4 services: Registration, Identification, Search and Recovery. Each of these services has two mandatory dependencies:

• repository (that implements Palladium\Contract\CanPersistIdenity)
• logger (that implements Psr\Log\LoggerInterface)

This gives you an option to replace the default repository, if you want to alter or replace parts of persistence abstraction layer. As for logger - the recommended approach is to use Monolog, but it would work with any compatible logging system.

The default repository also comes with functionality for adding custom identity types and data mappers, that are used for either your or the built-in identity types. For usage details see %TODO% section.

Optional parameters

In the constructor of Identification service there is an optional third and fourth parameter:

• lifespan of the cookie (in seconds), which defaults to 4 hours.
• hash cost (for BCrypt), which defaults to 12

In the constructor of Registration service there is an optional third parameter:

• hash cost (for BCrypt), which defaults to 12

Setting up the repository

As noted above, all 4 of the services expect a repository as a constructor dependency. If you are not replacing the bundled repository with your custome version, then you will need to initialize Palladium\Repository\Identity and pass it to the services.

The bundled repository itself has a single dependency: instance, that implements Palladium\Contract\CanCreateMapper. This contract (interface) is implemented by Palladium\Component\MapperFactory. And this factory has two dependencies: PDO instance and the name of table, where the identities will be stored.

<?php

$factory = new \Palladium\Component\MapperFactory(new \PDO(...$config), $tableName);
$repository = new \Palladium\Repository\Identity($factory);

In every other code example, where you see $repository variable used, you can assume, that it has been initialized using this code sample.

Use with DI containers

For users of Symfony's DependencyInjection Component (version: 3.4+), there is a sample configuration file: %TODO%

Usage

Registration of new identity

<?php

$registration = new \Palladium\Service\Registration($repository, $logger);

$identity = $registration->createStandardIdentity('foo@bar.com', 'password');
$registration->bindAccountToIdentity($accountId, $identity);

If operation is completed successfully, the $identity variable will contain an instance of unverified StandardIdentity. To complete verification, you will have to use the token, that the identity contains. In the give example, this token can be assessed using $instance->getToken().

The createStandardIdentity() method can throw IdentityConflict exception, if email has already used for a another identity.

The createStandardIdentity() method has an optional third parameter, that defines the lifespan on the email verification token in seconds. When applied, the previous example looks as following:

<?php

$registration = new \Palladium\Service\Registration($repository, $logger);

$identity = $registration->createStandardIdentity('foo@bar.com', 'password', 3600);
$registration->bindAccountToIdentity($accountId, $identity);

This will make the verification token usable for 1 hour after this user's identity has been registered. After that given time passes, you won't be able to find this identity using the findStandardIdentityByToken() in the Search service.

IMPORTANT: the createStandardIdentity() methods does not validate users email or any other type of identifier. It only checks its uniqueness. Validation of emails, phone numbers, nicknames and other identifiers is beyond the scope of this library.

Verification of an identity

<?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);

The $token value is used to locate the matching EmailIdentity, which then gets verified. If the identity is not found, the findStandardIdentityByToken() will throw IdentityNotFound exception.

Login with email and password

<?php

$search = new \Palladium\Service\Search($repository, $logger);
$identification = new \Palladium\Service\Identification($repository, $logger);

$identity = $search->findStandardIdentityByIdentifier($identifier);
$cookie = $identification->loginWithPassword($identity, $password);

If there is no matching identity with given idenitifier (like, email address) found, the findStandardIdentityByIdentifier() method will throw IdentityNotFound exception.

In case, if password does not match, the loginWithPassword() method will throw PasswordMismatch exception.

Creation of new single-use login

<?php

$identity = $this->registration->createNonceIdentity($accountId);

This will create a new instance of NonceIdentity. To use it for login, you will need values in NonceIdentity::getIdentifier() and NonceIdentity::getKey(), where the identifier will be used to locate the nonce identity and key will be used to verify.

The createNonceIdentity() method was an optional second parameter, that defines the lifespan this single-use identity in seconds. When applied, the previous example looks as following:

<?php

$identity = $this->registration->createNonceIdentity($accountId, 600);

This will make the single-use identity usable for 10 minutes after its creation. After the allowed time has passed, passing this identity in useNonceIdentity() method of Identification will result in IdentityExpired exception being thrown.

Login with nonce

<?php

$identity = $this->search->findNonceIdentityByIdentifier($identifier);
$cookie = $this->identification->useNonceIdentity($identity, $key);

If there is no matching identity with given identitifier (email address, nickname, ect.) found, the findNonceIdentityByIdentifier() method will throw IdentityNotFound exception.

In case, if password does not match, the useNonceIdentity() method will throw KeyMismatch exception.

Login using cookie

<?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);

If cookie is not found using findCookieIdentity() a standard IdentityNotFound excep