Permissions

Introduction

The BF has embedded native methods to support restricted sections of your application and authentication resources. The first step in using those native methods is, basically, tells BF which of your URLs requires authentication. And to do that, you just need to add such URL entries in the $restriction in their config.inc.php.
 

Restricted Sections

So, if a request is performed to a restricted URL, the BF will return a permission denied in case the user is authenticated, but has no permission to access the section or will redirect him to the login page, in case he is not authenticated yet.

Full restriction

To create a full restriction you need to add a new entry in the $restriction. Each entry will be considered recursively, for example:

If the URL below is restricted.
http://localhost/clients

Then all recursive URL will be automatically restricted.
http://localhost/clients/1http://localhost/clients/edithttp://localhost/clients/profilehttp://localhost/clients/x/y/z


In practical terms, to have the URL (http://localhost/clients) restricted you need to have the following entry in your config.inc.php

$restriction = array(
                    'clients' => array('title'=>'Clients Module')
                    );

Partial restrictions

Let'ss consider the following example:

$restriction = array(
                             'admin'               => array('title'=>'Admin'),
                             'clients/profile'     => array('title'=>'Client profile'),
                             'clients/edition'     => array('title'=>'Client edition'),
                    );

For the configuration above, the URL (http://localhost/clients) will open normally since it is not restricted, but on the other hand, only authenticated users with permissions to these sections can access http://localhost/clients/profile or http://localhost/clients/edition

Using this type of configuration, developers can allow users to have partial access to sections in their applications. For example, a group of users can have access to http://localhost/clients/profile but not http://localhost/clients/edition

 

Permissions

Using the BF Admin Page (http://localhost/admin) you can create users and permission rules. Basically, through the permission management section, it is possible to give or not give permission to users for each URL entry available in the $restriction array in their config.inc.php.

 

 

So, each permission can be defined in this module by:

Description: the name o the group;
Status: status of the group;
Hierarchy: importance of the group in the application;
Superuser: a user in the group superusers can have access to all sections;
Permissions: access condition to every single restricted URL entry; ($restriction defined on config.inc.php)

 

NOTE: A new restricted URL added or permission changed won't immediatly affect authenticated users. So, in order to users get the new configuration, they will need to authenticate again.

 

Login

The login() method is available in your module and controllers inherited from the Module Library. Basically, the method is responsible for the authentication methods, including:

  1. username and password validation;
  2. password recovery;
  3. new user email validation;
     

How it works

All user information are stored in the users table. And, it is important to know that there is no native methods for users to perform their own registration, since is a very custom requirement and varies from application to application. But, you can find some available methods in the Users Model to help you create your own.

There are some important columns in the users table, such as:

The user_status column has the status of the user and means:

0: when the user is excluded
1: when the user is active
2: when the user's email was not confirm it;


The user_hash column has a temporary hash and means:

When the user_status is pending (2), the system is waiting for http://localhost/any_module/login?h=[hash] to confirm the user's email and change its user_status to active (1).

When the user_recovery is (1), the system is waiting for http://localhost/any_module/login?h=[hash] to force the login without credentials. This happens when the user forgets his password and is important to know the link works only once.

In any other circunstance the user_hash column is used to validate the cookies and helps the persisted authentication features.

 

The user_locale column has the the user preferable locale:

The value is the identification of the dictionary to be used in case of a multi-language application.

 

NOTE: This should be a very straight forward concept, but nothing better then an good example of use. So, the module Me.class.php (http://localhost/me) can be used as a complete example of the user own registration and can be used as a reference for your own developments.

 

Logout

The logout() method is available in your module and controllers inherited from the Module Library. The method can be called by a URL request or from your code, and once is called all session, cookies are destroyed.

<?php

namespace modules\Clients;

use bossanova\Module\Module

class Clients Extends Module
{
    public method anyMethod ()
    {
        // Logout from the system
        $this->logout()
    }
}

A direct URL call is available in any module, for example: http://localhost/clients/logout

 

Identification

Get user ID

To get the user_id from an authenticated user, you can use the method getUser(). For example:

<?php

namespace modules\Clients;

use bossanova\Module\Module;

class Clients Extends Module
{
    public method __default ()
    {
        // Get the user_id
        $user_id = $this->getUser();

        // Do something...
    }
}

Get user ID or call the login page

The method getIdent() returns the user ID, but if the user is not authenticated yet, will be redirected to the login page, for example:

<?php

namespace modules\Clients;

use bossanova\Module\Module;

class Clients Extends Module
{
    public method __default ()
    {
        if ($user_id = $this->getIdent()) {
            // Do something...
        }
    }
}

Check permissions

Get all permissions from an authenticated user

$this->getPermissions(); // Return an array with all permissions
 

Check the permission for a section

$this->getPermissions('clients/profile'); // True if the user has access to http://localhost/clients/profile
$this->getPermissions('clients/test');
$this->getPermissions('clients/any/path');