Skip to content

Latest commit

 

History

History
191 lines (140 loc) · 9.11 KB

index.md

File metadata and controls

191 lines (140 loc) · 9.11 KB
Raw

Laravel Authentication ACL documentation

Laravel Authentication ACL is a Laravel 4 package, based on sentry2.
This package is made with the purpose to help developer setting up a simple admin panel with an ACL using Laravel framework.

Table of Contents

  1. Requirements
  2. Setup
  3. Configuration
  4. Usage
  5. Advanced Configuration and API

Requirements

To install this software you need:

  • Laravel framework 4.*
  • Php 5.4+

Setup

To install authentication follow this steps:

  1. Create an empty Laravel 4 installation if you don't have any.

  2. Add to your composer.json require field the following lines:

    "require": {
  ...
  "jacopo/laravel-authentication-acl": "1.1.1"
},

  3. Now run composer update command.

  4. Now open the file app/config/app.php and add to the 'providers' option the following line: 'Jacopo\Authentication\AuthenticationServiceProvider',

  5. Then run this command to publish the configuration files: php artisan authentication:prepare Now you can find configuration files in app/config/packages/jacopo/authentication folder. If you want to use a custom db(database) access configuration only for this package (while keeping other db connections for the rest of the application) edit the app/config/packages/jacopo/authentication/database.php file.

  6. Now you need to install the application, to do that run the command: php artisan authentication:install.

Congratulations! You have succesfully installed Laravel Authentication ACL package!

Here is the main application links:

  • http://url_of_your_application/login the client login page (after logging in will redirect you to the home page) [ username:admin@admin.com password:password ]
  • http://url_of_your_application/admin/login the admin login page (after logging in will redirect you to the admin panel) [ username:admin@admin.com password:password ]
  • http://url_of_your_application/user/signup the new user signup form (to register a new user)
  • http://url_of_your_application/user/logout the logout page

Note on sending emails

Keep in mind this software will send various notification emails, dont't forget to edit your laravel app/config/mail.php file.

Configuration

After installing the package you can find all his configuration files under the folder: app/config/packages/jacopo/authentication. All the files are self documented, here is a brief overview of each configuration file:

  • sentry/config.php: the low level authentication configuration part, it helps you handle session cookie's name,login throttling and custom password hashing
  • way-form/config.php: system configuration files for form handling (do not edit)
  • config.php: basic configuration
  • menu.php: to create dynamic admin menu with arbitrary permissions
  • database.php: custom database configuration file
  • permission.php: general permissions configuration

Usage

You have four main link to access the application.

The first is the user login page available at: http://url_of_your_application/login. With the user login page (after login) you will be redirected to the root application folder: "/" The second main link is the admin login page, available at http://url_of_your_application/admin/login. Here is the sceenshoot of the admin login page:

After the login you will be redirected to the admin panel:

The main panel contains three main menu links(on top): users, groups and permissions. Following this link you will be redirected to the corresponding area. On every page you may see a panel to filter the results in the list (on the right) and a sidebar on the left with the link to add a new resource or to list all the resources. If you want to create a new user you need to click on the add user/add new button:

After filling the form you can also create/edit a user profile with the edit profile link:

In the profile form you can setup an avatar for the user and also add custom profile fields. When you add a new custom field it will be added in all the user's profile form.
Attention: to add custom profile field an user need the permission set in the permission.php configuration file.

The listing/filtering and editing of groups and permission respect the same structure as for the users (just use the links on the main menu).

The third link is the user signup form available at: http://url_of_your_application/user/signup:

The last link is the logout link available at: http://url_of_your_application/user/logout

Permissions handling

Every user belongs to a certain number of groups(you can edit them in the user page). You can also define custom permission for user and groups. When the software search for permissions it will join the permission that are associated to the user, with the one of all the groups that belongs to the user; if the permissions to check for is in that list the check will pass otherwise it won't pass.

Advanced configuration and API

By installing the package you have two helper classes available anywhere in your application:

  • authentication : you can obtain this class with the following code: <?php $authentication = \App::make('authenticator'); ?> The class have the following methods:

                  `
              /**
              * Force authentication on a user
              *
              * @param array $credentials: an array with the following structure: ["email" => "user_email", "password" => "user_password"]
              * @param boolean $remember
              * @return mixed
              */
              public function authenticate($credentials, $remember);

              /**
              * @param $user
              * @param $remember
              * @return mixed
              */
              public function loginById($id, $remember);

              /**
              * Logout
              *
              * @return mixed
              */
              public function logout();

              /**
              * @return mixed
              */
              public function getErrors();

              /**
              * Obtain the user with his email
              *
              * @param $email
              * @return mixed
              * @throws \Jacopo\Authentication\Exceptions\UserNotFoundException
              * @return mixed
              */
              public function getUser($email);

              /**
              * Obtains a user given his user id
              *
              * @param $id
              * @return mixed
              */
              public function getUserById($id);

              /**
              * Obtain the current logged user
              *
              * @return mixed
              */
              public function getLoggedUser();
              `

You can find the user class in the file: vendor/jacopo/authentication/src/Jacopo/Authentication/Models/User.php

  • authentication_helper : you can obtain this class with the following code: <?php $authentication = \App::make('authentication_helper'); ?>

                  The class have the following methods:
              /**
              * Check if the current user is logged in and has any of the
              * permissions given in $permissions
              * @param array $permissions contain strings with the permissions name
              * @return boolean
              */
              public function hasPermission(array $permissions);`

Blocking editing of a user/group or permission for the admin ui

In case you want to block the editing of a user/group/permission from the admin ui you need to open any dbms editor (like phpmyadmin) and go to the relative row in the corrisponding table associated (users,groups,permission) and then set the flag of the column "protected" to "1".

How to run all tests

To run all the tests you need phpunit and sqlite3 installed on your system. Then go in vendor/jacopo/authentication folder and run the command: phpunit.