acl-config

name	acl-config
description	Guides the configuration of the Access Control List (ACL) in SimpleRest, including adjusting roles, inheritance, and resource permissions in config\acl.php. Use when this capability is needed.
metadata	{"author":"boctulus"}

ACL Configuration Skill

This skill guides you through adjusting the config/acl.php file based on project needs, managing roles, and configuring granular resource permissions.

Key Concepts

SimpleRest uses a multi-layered permission system:

• Roles: Logical groups of permissions (e.g., guest, registered, admin).
• Inheritance: Roles can inherit permissions from other roles.
• Special Permissions: Global system-wide permissions (e.g., read_all, write_all, impersonate, lock).
• Resource Permissions: Permissions specific to a table/resource (e.g., show, list, create, update, delete).

Step 1: Analyze Requirements

Before making changes, determine:

1. What roles are needed?
2. Which tables/resources need specific access control?
3. Should a role inherit from another?

Step 2: Modify config/acl.php

Open config/acl.php. Use the $acl object to define roles and permissions.

Defining Roles

$acl->addRole('vendedor', 10);

Inheriting Roles

[!IMPORTANT] addInherit() must be called before adding new permissions to the inheriting role.

$acl->addRole('vendedor', 10)
    ->addInherit('guest');

Adding Special Permissions

$acl->addSpecialPermissions(['read_all', 'write_all'], 'admin');

Adding Resource (Table) Permissions

Standard permissions: show, list, create, update, delete. Aliases: read (show + list), write (create + update + delete).

$acl->addResourcePermissions('products', ['read', 'create'], 'vendedor');

To allow access to records owned by others (e.g., for public listings or supervisors): show_all, list_all, read_all.

$acl->addResourcePermissions('posts', ['read_all'], 'guest');

Step 3: Set Guest and Registered Roles

Ensure the system knows which roles represent guests and registered users:

$acl->setAsGuest('guest');
$acl->setAsRegistered('registered');

Step 4: Regenerate ACL Cache

After modifying config/acl.php, you must regenerate the ACL cache:

php com make acl --force

To see the resulting ACL structure for debugging:

php com make acl --force --debug

Step 5: Verification

1. Check for syntax errors:

   php -l config/acl.php
   

2. Review output of the --debug command to ensure the roles and permissions are correctly mapped.
3. Verify via API: Test an endpoint with a specific role token to ensure permissions are enforced as expected.

Common Special Permissions

• read_all: Access records of other users.
• write_all: Modify/Delete records of other users.
• lock: Lock/Unlock records or modify locked records.
• grant: Conceder roles and permissions.
• impersonate: Ability to act as another user.
• fill_all: Modify non-fillable fields or creation dates.

Troubleshooting

• Inheritance Error: "You can't inherit permissions from 'X' when you have already permissions for 'Y'".
  • Solution: Call addInherit() immediately after addRole() and before addResourcePermissions() or addSpecialPermissions().
• Changes not reflecting:
  • Solution: Run php com make acl --force.
• 401/403 Errors:
  • Check if the user has the correct role assigned in the user_roles table.
  • Verify if a "decorator" permission in user_tb_permissions or user_sp_permissions is overriding the role.

---

Source: boctulus/simplerest — distributed by TomeVault.