README

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

Contributing
Report issues and send pull requests in the main Charcoal repository

charcoal / user

Maintainers

Details