Download the PHP package phpixie/auth without Composer

Auth

PHPixie Authentication library

This is the base package of the PHPixie authentication subsystem, which is split into several components. This manual covers all of them for.

Authentication is the most critical part of any application, implementing it the right way is hard, and any errors can compromise a lot of user, especially in opensource projects. Using old hash functions, cryptographically unsecure random generators and the misues of cookies are sadly things we still encounter frequently. This is why I spent a lot of time to carefully implement authentication in PHPixie.

What makes it secure

• Using the secure password_hash() in PHP 5.5 and a compatibilty package for older PHP versions
• Same for the crryptographically secure random_bytes() from PHP 7
• Following the best practices for persisted login

The last point is the most interesting and currently no other framework supports it out of the box. The idea behind it lies in the use of a special table for storing auth tokens.

1. When a user first logs in a random series identiefier and a passphrase are generated. These are then sent to the user as a cookie.
2. The series and passphrase are hashed, and then the series, the resulting hash, user id and expiration date are saved in the database
3. When a user enters the site (and the session is not already present) his cookie is rehashed and compared to the hash in the database. If those match, the user is logged in, a session is started and a new token is generated for the user.
4. If the hashes don't match a theft is assumed and any token with the same series identifier is deleted from the table

This approach has huge benefits when compared to the usual approach of storing a single token in the users table:

• Users can have multiple persistent session on multiple devices (each device will get its own series)
• Tokens are of one time use, and if stolen using a MITM attack cannot be reused.
• Tokens cannot be bruteforced, since the first unsuccessful attempt removes the series
• If a database is ever compromised, only token hashes are exposed, so the attacker still cannot login.

And basically if your framework is storing the paristent token as-is in the database without hashing it, it is comparable to storing an unhashed password there. And there are still a lot of popular frameworks doing this, just take a look.

Initializing

The initialization might seem a bit overwhelming, but that is because the architecture is highly modular and tries to minimize any unneeded dependencies. If you don't need a particular extension, feel free to not build it. Of course if you are using the PHPixie framework all of this is handled automatically.

Repositories

The first thing you need is a user repository. The most basic one is PHPixie\Auth\Repositories\Repository which only provides fetching users by their id. But for any practical use you will probably need the \PHPixie\AuthLogin\Repository interface, which allows for the password based login. You will need a repostory builder to pass to the Auth component:

Framework support

If you are using the PHPixie ORM all you need is to extend the premade wrappers:

Don't forget to register these wrappers with the ORM:

And register an AuthRepositories class in your bundle

Configuration options

The configuration is split into domains. A domain is a context that consists of a repository and authentication providers. Usually your app will have only a single domain, but sometimes you may need more. E.g. imagine you have some sort of the social login for site users, but site administrators are logged in on a separate page using their database accounts.

As you can see all providers are entirely independent of each other, whcih means we can alter the behavior easily. For example let's assume that we don't want to use sessions at all, just the cookie based login, and turn off token regeneration on each request:

Token storage

In both examples we referenced a database table used to store tokens. In fact this can also be a MongoDB collection. The SQL for the table creation would be as follows:

Usage example

Now that we have everything configured, lets test how it all works together. Here is a simple processor:

To test it try hitting these URLs:

1. /auth - user is not logged in
2. /auth/add?username=dracony&password=5 - add user to the database
3. /auth/login?username=dracony&password=5 - log in
4. /auth - check login
5. /auth/logout - logout

Adding your own providers

At some point you will probably need to add your own login providers (e.g. for social networks), to do that you need to satisfy a PHPixie\Auth\Providers\Builder interface and pass it along with the other extensions. Try looking at the AuthLogin component for an example. If you are using the PHPixie Framework you can pass your custom extensions to the Auth component by overloading this method.