README

This is Laravel 5 package for role-permission based authenticating.

Table of content

Features
Todo
Installation
Models
Helper classes
Middleware
Packages

Features

Permission based access
Grouping permissions (Roles)
Restrict routes access by individual permission(s) or role(s)
Allow to use same username, separated to individual namespaces (each namespace require individual login screen or option to specify namespace at login)

Todo

Fix incoming bugs
Finish documentation
Write tests
Cache metadata

Installation

Composer

There are multiple way to install package via composer

To your composer.json file add following lines:

// to your "require" object
"vi-kon/laravel-auth": "^3.0"

Or run following command in project root:
```
composer require vi-kon/laravel-auth
```
This command will add above line in your composer.json file and download required package files.

Setup

In your Laravel 5.1 project add following lines to config/app.php:

// to providers array
\ViKon\Auth\AuthServiceProvider::class,

Aliases

Optionally you can add aliases back to app.php:

// to aliases array
'RouterAuth' => \ViKon\Auth\Facades\RouterAuth::class,

Middleware

No need to assign short-hand key to App\Http\Kernel's routeMiddleware property, because AuthServiceProvider do it automatically. These middlewares are:

HasAccessMiddleware
LoginRedirectorMiddleware
PermissionMiddleware

Has Access middleware

Has access middleware can attach to groups or routes. This middleware check if route has assigned permission and if current user has permission to access that route.

Usage

Part of routes.php:

// Single route
Route::get('/', [
    'middleware' => 'auth.has-access',
    'permission' => 'access.some.controller',
    'uses'       => 'SomeController@index',

]);
// Multiple routes in group
Route::group(['middleware' => 'auth.has-access'], function () {
    // ...
    Route::get('/', [
        'permission' => 'access.some.controller',
        'uses'       => 'SomeController@index',
    ]);
    // ...
});

Login redirector middleware

This middleware allow to redirect user (if not authenticated) to custom login page. It is useful if users are separated to individual namespaces and some routes belongs to first namespace and some routes belongs to second namespace.

Permission middleware

Permission middleware get permission from their argument and restrict user if has no permission to access the route.

Models

All models have configurable database names. These database names are hold under table.* config value. In this short introduction default table names are used. The package holds following models:

User
Role
Permission
Group
UserPasswordReminder
Profile

Models are using pivot tables for many to many relations: rel__role__group, rel__user__role, rel__user__group.

Note: All table names, even pivot table names are configurable via config file.

Warning: Not recommended to change table names if database is already migrated, because migrations down method will try to execute on wrong tables.

User model

User representing model, implements AuthenticatableContract and CanResetPasswordContract interfaces and use Authenticatable and CanResetPassword traits.

Namespace: ViKon\Auth\Model

Database table: users

Read/Write Properties

Type	Name	Description	Default	Database
integer	`id`	Unique user identifier	-	primary key, increments
string	`username`	Username	-
string	`password`	User password	-	length 255
string	`email`	User e-mail address	-	length 255
string	`remember_token`	Remember token for "Remember me"	null	nullable
string	`package`	Package name	"system"	length 255
string	`home`	User home route name	null	nullable
boolean	`blocked`	Check if user is blocked	false
boolean	`static`	Disallow deleting on GUI	false
boolean	`hidden`	Disallow showing on GUI	false

The username and package columns has contracted unique index.

Read properties (relations)

Type	Name	Description	Default	Database
\ViKon\Auth\Model\Role[]	`roles`	Roles collection	-	many to many relation with `user_roles` table
\ViKon\Auth\Model\Permission[]	`permissions`	Permissions collection	-	many to many relation with `user_permissions` table
\ViKon\Auth\Model\Reminder[]	`reminders`	Reminders collection	-	many to many relation with `user_password_reminders` table

Methods (relations)

Relations for Laravel Query Builder.

Type	Name	Description	Database
BelongsToMany	`roles()`	Users relation for query builder	many to many relation with `user_roles` table
BelongsToMany	`permissions()`	Permissions relation for query builder	many to many relation with `user_permissions` table
BelongsToMany	`reminders()`	Reminders relation for query builder	many to many relation with `user_password_reminders` table
HasOne	`profile()`	Return attached user profile	one to one relation to `user_profile` table (this table can customized via custom Profile model)

Role model

Role is for managing user permissions as collection. So this is a helper to add multiple permissions to user. Each role can contain multiple permissions.

Namespace: ViKon\Auth\Model

Database table: user_roles

Read/Write Properties

Type	Name	Description	Default	Database
integer	`id`	Unique role identifier	-	primary key, increments
string	`token`	Unique role name (token)	null	unique, nullable
boolean	`static`	Disallow deleting on GUI	false
boolean	`hidden`	Disallow showing on GUI	false

Read properties (relations)

Type	Name	Description	Default	Database
\ViKon\Auth\Model\User[]	`users`	Users collection	-	many to many relation with `users` table
\ViKon\Auth\Model\Permission[]	`permissions`	Permissions collection	-	many to many relation with `user_permissions` table

Methods (relations)

Relations for Laravel Query Builder.

Type	Name	Description	Database
BelongsToMany	`users()`	Users relation for query builder	many to many relation with `users` table
BelongsToMany	`permissions()`	Roles relation for query builder	many to many relation with `user_permissions` table

Permission model

Permissions is for granting some kind of access to users, like access routes or certain actions. Each action should have individual permissions.

For example in REST controller should have {action name}.index, {action name}.show {action name}.create, {action name}.edit and {action name}.destroy permissions for individual actions.

Namespace: ViKon\Auth\Model

Database table: user_permissions

Read/Write Properties

Type	Name	Description	Default	Database
integer	`id`	Unique permissions identifier	-	primary key, increments
string	`token`	Unique permissions token	-	unique

Read properties (relations)

Type	Name	Description	Default	Database
\ViKon\Auth\Model\User[]	`users`	Users collection	-	many to many relation with `users` table
\ViKon\Auth\Model\Role[]	`roles`	Roles collection	-	many to many relation with `user_roles` table

Methods (relations)

Relations for Laravel Query Builder.

Type	Name	Description	Database
BelongsToMany	`users()`	Users relation for query builder	many to many relation with `users` table
BelongsToMany	`roles()`	Roles relation for query builder	many to many relation with `user_roles` table

UserPasswordReminder model

Stores password reminder tokens with store time.

Namespace: ViKon\Auth\Model

Database table: user_password_reminders

Read/Write Properties

Type	Name	Description	Default	Database
integer	`id`	Unique reminder identifier	-	primary key, increments
integer	`user_id`	User id	-	index
string	`token`	Password token	-
Carbon	`created_at`	Created at time	-

Read properties (relations)

Type	Name	Description	Default	Database
\ViKon\Auth\Model\User	`user`	User model	-	many to one relation with `users` table

Methods (relations)

Relations for Laravel Query Builder.

Type	Name	Description	Database
BelongsTo	`user()`	User relation for query builder	many to many relation with `users` table

Profile model

Profile model is not implemented in this package. This is only for support to add custom data to users via single one to one relation. In config with profile option can customize Profile model location.

Profile model has only one restriction. Need to have user_id column, which is point to User's model id column.

Short example for profile migration file:

class CreateProfileTable extends Migration
{
    public function up()
    {
        Schema::create('user_profile', function (Blueprint $table) {
            $table->engine = 'InnoDB';

            $table->increments('id');

            // Foreign connection to user table
            $table->unsignedInteger('user_id')
                  ->unique();
            $table->foreign('user_id')
                  ->references('id')
                  ->on('users')
                  ->onUpdate('cascade')
                  ->onDelete('cascade');
        });
    }

    public function down()
    {
        Schema::drop('user_profile');
    }
}

Guard class

The Guard class extends Laravel's default Guard class to grant access for new features. These features allow to get permission for current user, check if user is blocked or not.

Methods

Some methods are not newly implemented, just overwritten.

attempt - try to authenticate user with credentials (auto inject into credentials default role package if set)
hasPermission - check if authenticated user has a specific permission
hasPermissions - check if authenticated user has multiple permissions at once
isBlocked - check if authenticated user is blocked or not
user - get authenticated user

TODO method descriptions

RouterAuth class

The RouterAuth class allow to get authentication information from route.

Methods

hasAccess - get roles for a named route
isPublic - check if current user has access to named route
getPermissions - check if route is public (route has no permissions)

TODO method descriptions

Middleware

Middleware classes allow to filter individual routes by their attached permissions.

HasAccessMiddleware - check if authenticated user have single or multiple permissions to current route
HasAccessMiddleware - check if authenticated user have single permission to current route

Note: Syntax is only difference between these middlewares.

PermissionMiddleware middleware

Note: The router cannot get parameter from this middleware.

HasAccessMiddleware middleware

Check if authenticated user have all permissions to current route. To add permission(s) to route only need add permissions key to route options with right permissions.

Router::get('/', [
    'permissions' => 'permission.name',
]);

Or if multiple permissions are passed (Authenticated user have to has all permissions to access route):

Router::get('/', [
    'permissions' => [
        'permission.first.name',
        'permission.second.name',
    ],
]);

Note: If current route's permissions key is empty or not exists, then route is mark as public and no route restriction will made.

Configuration

With php artisan vendor:publish --provider="ViKon\Auth\AuthServiceProvider" --tag="config" command you can publish all config files to vi-kon/auth.php.

In this file there are multiple options. The following options are available:

login.route - login screen route name
error-403.route - route name if user is already authenticated but has no access to route

If user is not authenticated and route is not public, then middlewares redirect user to named route, where named route name is stored in login.route config value.

If user is authenticated and hasn't got enough permissions to access route, then middlewares redirect to named route stored in error-403.route config value.

Otherwise middlewares allow access to route.

Note: The login.route and error-403.route stores the route name.

On 403 error the following parameters are flashed to session during redirect:

route-request-uri - with full URL
route-roles - array with list of roles needed by route

Usage

// check if user have "admin" role
$options = [
    'middleware'  => 'auth.role',
    'permissions' => 'admin',
];
Route::get('URL', $options);

// check if user have "admin" and "superadmin" roles
$options = [
    'middleware'  => 'auth.role',
    'permissions' => ['admin', 'superadmin'],
];
Route::get('URL', $options);

Namespaces

Namespaces are useful for grouping users into individual login groups. In each namespace usernames are unique, however in other namespace using the same username is permitted.

The default package is system. All users are stored in this package.

Authentication

For authenticating user in default namespace is simple, just call attempt method as usual:

if (Auth::attempt(['email' => $email, 'password' => $password]))
{
    return redirect()->intended('dashboard');
}

For authenticating in custom namespace, need to provide namespace name:

if (Auth::attempt(['email' => $email, 'password' => $password, 'namespace' => $namespace]))
{
    return redirect()->intended('dashboard');
}

License

This package is licensed under the MIT License

vi-kon / laravel-auth

Maintainers

Details

README

Table of content

Features

Todo

Installation

Composer

Setup

Aliases

Middleware

Has Access middleware

Usage

Login redirector middleware

Permission middleware

Models

User model

Read/Write Properties

Read properties (relations)

Methods (relations)

Role model

Read/Write Properties

Read properties (relations)

Methods (relations)

Permission model

Read/Write Properties

Read properties (relations)

Methods (relations)

UserPasswordReminder model

Read/Write Properties

Read properties (relations)

Methods (relations)

Profile model

Helper classes

Guard class

Methods

RouterAuth class

Methods

Middleware

PermissionMiddleware middleware

HasAccessMiddleware middleware

Configuration

Usage

Namespaces

Authentication

License