README

Local authentication module for the Daedalus web application framework.

Installation

This module is typically used as part of a Daedalus web application. If you'd like to use it on your own non-Daedalus project, you can add the following to your composer.json file:

{
  "require": {
    "daedalus-web/authentication": "^2.0"
  }
}

Usage

This module handles user registration and login.

// Register a new account -- just replace the POST variables below with however you collect from the login form
$credentials = [
    'user_name' => $_POST['user_name'],
    'password'  => $_POST['password']
];
$id = User::register($credentials);

// Logging a user in (using the same $credentials array)
$user = User::login($credentials);

Password Security

Once a plaintext password is passed into the User::register method, it is hashed using the default password_hash() function in your version of PHP. This typically uses the BLOWFISH method of hashing, which is considered secure.

By default, the hash is computed by password_hash() using $options['cost'] = 10. You can increase this value by specifying a different DAEDALUS_AUTHENTICATION_HASH_COST in your .env file. The higher your cost, the more computation is required but the more secure your password is. Test various costs to find what works best in your production environment. We do not recommend going below $options['cost'] = 10, which is the default.

User Details

You can provide an arbitrary array of User Details that you'd like to store during the registration process. Some things you may want to consider storing:

Email Address
Age or Date of Birth
Opt-In to a newsletter
Nickname

To save User Details during the registration process, just pass an associative array of user details as a second parameter to User::register().

$details = [
  'email_address'     => 'placeholder@example.com',
  'newsletter_opt_in' => 'true',
  'donor_status'      => 'past-donor'
];
$id = User::register($credentials, $details);

User Roles and Permissions

Permissions are role-based. Either a user has a role, and can access something, or they do not. To create a new role:

$role_details = [
  'description' => 'Customer with an active subscription',
  'name'        => 'subscriber'
];
Role::create($role_details);

To add or remove a role from a user:

User::addRole($userID, Role::get('subscriber'));
User::removeRole($userID, Role::get('subscriber'));

To verify if a user has a role, you can use:

User::isApproved('subscriber');

// You can also pass multiple options instead of using OR logic, of which the user only needs to satisfy one
User::isApproved(['subscriber', 'lifetime_pass', 'vip']);

About

Requirements

Daedalus Authentication is fully tested to work with:

PHP 7.0
PHP 7.1

Daedalus Authentication will not work on PHP 5.4 or earlier. This module makes use of the PHP built-in functions password_hash() and password_verify(), which were implemented in PHP 5.5.

Strictly speaking, this module can be modified to support PHP 5.5+, however we use strict variable typing that is not available in PHP versions before 7.0. Because PHP 5.6 is no longer receiving active support (and will only be receiving security updates for another year), we strongly recommend starting any new project with PHP 7 or later.

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub

Author

Josh Grancell - josh@joshgrancell.com - https://github.com/jgrancell

License

Daedalus Authentication is licensed under the MIT License - see the LICENSE file for details

daedalus-web / authentication

Maintainers

Details