README

HierAuth 是一个简单的 CakePHP 3 层次性 ACL 授权插件。您可以根据角色授予和拒绝访问权限，并创建虚拟角色以包含子角色。

安装

使用 composer 安装插件

composer require btaens/cakephp-hier-auth

将以下行插入到您的 config/bootstrap.php 文件中

Plugin::load('HierAuth');

设置

通过 AuthComponent 加载和配置 HierAuth

$this->loadComponent('Auth', [
    'authorize' => [
        'HierAuth.Hier' => [
            'hierarchyFile' => 'hierarchy.yml',
            'aclFile' => 'acl.yml',
            'roleColumn' => false,
            'roleKeys' => [
                'roles' => [
                    'multi' => true,
                    'column' => 'label',
                ],
            ],
        ],
    ],
]);

层次结构和 ACL

hierarchyFile 是一个定义您角色层次结构的 YAML 文件。将其放在您的 config 目录中。其基本结构如下

hierarchy:
   ROOT:
       - DEVELOPER
       - OWNER
   MODERATOR:
       - FINANCE
       - LABOR
   ADMIN:
       - "@MODERATOR"
       - SALES
       - CONTACT
   USER:
       - MEMBER

这里定义了一个根角色。根角色不一定是用户实际拥有的角色，但任何拥有 DEVELOPER 或 OWNER 角色的用户都将获得访问根角色权限的任何路由。

ADMIN 也包括 @MODERATOR。这意味着 MODERATOR 中的所有角色都将拥有 ADMIN 的所有访问（或拒绝）权限。您也可以递归地（最多10层）这样做，因此一个角色可以包含另一个角色，该角色又可以包含另一个角色。

如果不需要为角色设置层次结构，则不需要将所有角色写入层次结构文件，您还可以为未在此列出的角色授予和拒绝访问权限。

您还可以包含现有角色，并授予它们其他现有角色的访问权限

hierarchy:
    SALES:
        - CONTACT

在这种情况下，所有拥有 CONTACT 角色的用户都将获得 SALES 角色的所有访问权限。

aclFile 是一个定义您要授予或拒绝路由访问权限的 YAML 文件。将其放在您的 config 目录中。其基本结构如下

controllers:
    ALL: [ROOT, ADMIN]
    Posts:
        ALL: [MODERATOR, -ADMIN, CONTACT]
        index: [USER, NEWBIE]

您希望定义访问权限的控制器位于 controllers 键下。大写的 ALL 键（全部大写）定义了对所有子成员的访问（在 controllers 下对所有控制器，在各个控制器下对所有操作（即使未列出））。

根据此示例，默认情况下，ROOT 和 ADMIN 被授予访问所有控制器和操作（即使未列出）的权限。

Posts 的所有操作都由 MODERATOR 获得访问权限，但是 Posts 中所有操作对 ADMIN 都被拒绝（- 表示拒绝访问），除了 CONTACT，它也被授予访问权限。从这一点可以看出，顺序很重要（[CONTACT, -ADMIN] 意味着拒绝 CONTACT，因为该角色在 ADMIN 中被拒绝，但是 [-ADMIN, CONTACT] 授予 CONTACT 访问权限，因为我们首先拒绝所有在 ADMIN 中，然后授予 CONTACT）。

表设置

HierAuth 可以从多个表中获取用户的角色，所有这些表都可以通过 hasMany 或 hasAndBelongsToMany 关联，甚至可以直接通过用户表的一个列，作为 JSON 字段。

如果您正在使用用户表中的某列来设置用户角色，您必须将角色以JSON编码的形式保存，或者通过dataType操作返回它们，形式为数组（例如，具有DEVELOPER和MEMBER角色的用户将有一个名为roles的列，其值为：["DEVELOPER","MEMBER"]。然后，您将上面的配置中的roleColumn设置为列名：'roleColumn' => 'roles'。

然而，更推荐的方式是将角色存储在单独的表中，并与用户表关联。在下面的roleKeys配置键中传递您想使用的关联

'roleKeys' => [
    'roles' => [
        'multi' => true,
        'column' => 'label',
    ],
    'right' => [
        'multi' => false,
        'column' => 'label',
    ],
],

对于每个关联，您必须通过multi键提供用户是多角色还是单角色，该键是true或false。column键是HierAuth从其中读取角色标签的列（您在acl和hierarchy配置中编写的）。这可以是'id'，但更详细的唯一列推荐用于可读性（以及可维护性，如果您以后想移动数据库且角色表恰好以不同的id开头，您必须重写整个ACL角色配置）。

无论您选择定义哪种关联，您都必须确保它们在用户通过任何认证方法登录时保存在会话中。您需要编写一个自定义查找方法来确保包含正确数据。

$this->loadComponent('Auth', [
    'authenticate' => [
        'Form' => [
            'finder'=>'AuthUser'
        ],
    ],
]);

// In your UsersTable
public function findAuthUser(Query $query, $options)
{
    $query->contain([
        'Roles',
        'Rights'
    ]);
    return $query;
}

要求

• PHP >= 5.4.16
• CakePHP >= 3.0
• Symfony/YAML >= 2.6

未来计划

• 创建一个组件，用于检查用户的角色是否通过某个特定超级角色
• 创建一个与上面类似的助手

灵感来自dereuromark的TinyAuth。