Skip to content

[READ-ONLY] User definition, authentication and authorization

License

Notifications You must be signed in to change notification settings

charcoalphp/user

Repository files navigation

Charcoal User

The User package provides abstract tools for defining user models, authenticating and authorizating users from an integration with Laminas Permissions ACL.

Installation

composer require charcoal/user

Overview

The User object

At the core of this module is the definition of a "User" object. The contract can be found as \Charcoal\User\UserInterface. This interfaces extends \Charcoal\Object\ContentInterface (from charcoal/object), which extends \Charcoal\Model\ModelInterface (from charcoal/core).

The preferred way of using this module is by defining your own User class in your project and extending the provided \Charcoal\User\AbstractUser class.

For quick prototypes or small projects, a full concrete class is provided as \Charcoal\User\GenericUser.

User properties

Property Type Default Description
username string true
password string null
email string null
roles string[] [] ACL roles, which define user permissions.
last_login_date date-time null
last_login_ip string ''
last_password_date date-time null
last_password_ip string ''
login_token string null

Note that the key of the User is the username. Therefore, id() returns the username. It must be unique.

Properties inherited from Content-Interface:

Property Type Default Description
active boolean true
position number null
created date-time null
created_by string ''
last_modified date-time null
last_modified_by string ''

Authentication

TODO

Authorization

User authorization is managed with a role-based Access Control List (ACL). Internally, it uses laminas/laminas-permissions-acl for the ACL logic. It is recommended to read the Laminas ACL documentation to learn more about how it all works.

There are 2 main concepts that must be managed, either from JSON config files or in the database (which works well with charcoal/admin), roles and permissions.

ACL Configuration

To set up ACL, it is highly recommended to use the \Charcoal\User\Acl\Manager.

ACL Example

{
    "acl": {
        "permissions": {
            "superuser": {
                "superuser": true
            },
            "author": {
                "allowed": {},
                "denied": {}
            }
        }
    }
}
use Charcoal\User\Acl\Manager as AclManager;
use Laminas\Permissions\Acl\Acl;
use Laminas\Permissions\Acl\Resource\GenericResource as AclResource;

$acl = new Acl();

 // Add resource for ACL
$acl->addResource(new AclResource($resourceName));

$aclManager = new AclManager([
    'logger' => $logger,
]);
$aclManager->loadPermissions($acl, $config['acl.permissions'], $resourceName);

$authorizer = new Authorizer([
    'logger'   => $logger,
    'acl'      => $acl,
    'resource' => $resourceName,
]);

$isAllowed = $authorizer->userAllowed($user, [ 'permssion' ]);

Resources