Adapters

The Caridea\Auth\Service class uses adapters to abstract away the implementation details of storing user information.

Included with this library are three adapters for authentication through MongoDB, PDO, and X.509 client SSL certificates. You can easily write your own adapter for other authentication sources like IMAP, LDAP, or OAuth2 by implementing the Caridea\Auth\Adapter interface.

MongoDB

The adapter for MongoDB requires a few connection details. The MongoDB\Driver\Manager, the collection name, the name of the field containing the username, and the name of the field containing the password hash. There are also two optional parameters: an array to use as a query to limit user accounts (such as those that are not blocked), and finally a MongoDB\Driver\ReadPreference.

$manager = new \MongoDB\Driver\Manager("mongodb://localhost:27017");
$collectionName = "users";
$fieldUser = 'email';
$fieldPassword = 'password';
$query = ['active' => 1];
$rp = new \MongoDB\Driver\ReadPreference(\MongoDB\Driver\ReadPreference::RP_NEAREST);
$adapter = new \Caridea\Auth\Adapter\MongoDb(
    $manager,
    $collectionName,
    $fieldUser,
    $fieldPassword,
    $query, // optional
    $rp // optional
);

This adapter expects the $_POST values to be contained in the keys username and password. It also expects the password stored in the MongoDB collection to be one generated by password_hash.

PDO

The adapter for PDO requires a few connection details. The PDO object, the name of the column containing the username, the name of the column containing the password hash, and the table name. It has one optional parameter: a WHERE clause to limit user accounts (such as those that are not blocked).

$pdo = new PDO("mysql:host=localhost;dbname=DB;charset=UTF8");
$fieldUser = 'email';
$fieldPassword = 'password';
$tableName = 'user';
$where = "foo = 'bar'";
$adapter = new \Caridea\Auth\Adapter\Pdo(
    $pdo,
    $fieldUser,
    $fieldPassword,
    $tableName,
    $where // optional
);

This adapter expects the $_POST values to be contained in the keys username and password. It also expects the password stored in the MongoDB collection to be one generated by password_hash.

X.509 Certificates

The adapter for X.509 certificates has two optional parameters: The key within the $_SERVER parameters where the client certificate DN is available * If omitted, SSL_CLIENT_S_DN is the default A regular expression pattern that can be used to extract the username from the certificate DN * It must have only one capturing group * If omitted, the entire DN is used as the username

$fieldDn = 'SSL_CLIENT_S_DN';
$regex = '#/CN=(.+)$#';
$object = new Cert(
    $fieldDn,
    $regex
);
// this would extract the username 'Bob' from the DN '/O=Acme, Inc./CN=Bob'

This adapter does not need to validate passwords. With two-way encryption, there's no need!

Abstract Adapter

There is an abstract class, Caridea\Auth\Adapter\AbstractAdapter, which has several protected methods to simplify implementing your own adapter. All three provided adapters extend this abstract class.

• checkBlank – Used to ensure construction parameters are not blank, otherwise throws InvalidArgumentException.
• ensure – Used to ensure user-provided values are not blank, otherwise throws Caridea\Auth\Exception\MissingCredentials.
• verify – Uses the password_verify function to compare user-provided credentials with the stored hash, otherwise throws Caridea\Auth\Exception\InvalidPassword.
• details – Merges a provided associative array with default authentication details: the client's IP address, and the client's user agent string.