README

🔐 CakePHP Authorization Manager

Modern Role-Based Permission Management for CakePHP 5.x

A powerful, modern web interface for managing role-based permissions using CakePHP's Authorization plugin.

Features • Installation • Quick Start • Documentation • Migration

🌟 Features

🎯 Role-Based Access Control

Simple yet powerful RBAC system with role priorities and hierarchical permission management.

🔄 Auto-Discovery

Automatically scans your application for controllers and actions—no manual configuration needed.

🎨 Modern UI

Beautiful Bootstrap 5 interface with intuitive permission matrices and visual role management.

🌍 Multilingual Support

Built-in i18n support with Spanish and Galician translations ready to use.

⚡ High Performance

Built on CakePHP's Authorization plugin with permission caching for optimal performance.

🛡️ Secure by Default

Strict permission checking mode with comprehensive authorization middleware integration.

🚀 CakePHP 5.x Native

Fully compatible with CakePHP 5.x using modern Authorization instead of deprecated ACL.

💡 Why Authorization Manager?

Traditional ACL systems (acos/aros) are deprecated in CakePHP 5.x. This plugin provides:

✅ Modern Authorization - Uses CakePHP's official Authorization plugin
✅ Simplified Structure - No more complex ACO/ARO trees
✅ Visual Management - Web interface for managing permissions
✅ Role-Based - Industry-standard RBAC pattern
✅ Easy Integration - Drop-in authorization solution
✅ Multilingual - Spanish and Galician translations included

📋 Requirements

Requirement	Version
PHP	≥ 8.1
CakePHP	≥ 5.0
CakePHP Authorization	≥ 3.0

🚀 Installation

Step 1: Install via Composer

composer require mgomezbuceta/cakephp-aclmanager
composer require cakephp/authorization

Step 2: Load the Plugin

Add to your src/Application.php:

public function bootstrap(): void
{
    parent::bootstrap();

    $this->addPlugin('AclManager', ['bootstrap' => true, 'routes' => true]);
}

Step 3: Run Migrations

bin/cake migrations migrate -p AclManager

Step 4: Sync Resources

Visit /authorization-manager and click "Sync Resources" to discover all your controllers and actions.

That's it! 🎉

⚡ Quick Start

Basic Setup

Create Roles
- Visit /authorization-manager/roles
- Click "New Role"
- Create roles like: Administrator, Editor, Viewer
Assign Permissions
- Click "Manage Permissions" for a role
- Check/uncheck permissions for each controller/action
- Click "Save Permissions"
Integrate with Your Auth

// In your AppController or specific controller
public function initialize(): void
{
    parent::initialize();

    $this->loadComponent('AclManager.AuthorizationManager', [
        'userModel' => 'Users',
        'roleField' => 'role_id'
    ]);
}

public function isAuthorized($user = null): bool
{
    return $this->AuthorizationManager->isAuthorized($user);
}

Add role_id to Your Users Table

ALTER TABLE users ADD COLUMN role_id INT NOT NULL;
ALTER TABLE users ADD FOREIGN KEY (role_id) REFERENCES roles(id);

📚 Documentation

🔧 Configuration Options

Admin Access Control

IMPORTANT: By default, only administrators can access the Authorization Manager.

The plugin checks if the user is an admin using multiple methods (in order):

role_name: Checks if role_name is 'admin', 'administrator', or 'superadmin'
role_id: Checks if role_id == 1 (typically admin role)
is_admin: Checks if is_admin flag is true
email: Checks against a whitelist of admin emails

To customize admin access, add to your config/app.php in the return array:

// In config/app.php, add to the return array:
return [
    // ... existing configuration ...

    'AclManager' => [
        'adminAccess' => [
            // Which role IDs can access the Authorization Manager
            'adminRoleIds' => [1, 2],  // Allow role IDs 1 and 2

            // Which role names can access
            'adminRoleNames' => ['admin', 'superuser'],

            // Specific emails (useful for initial setup)
            'adminEmails' => [
                'admin@example.com',
            ],
        ],
        'redirects' => [
            'login' => ['controller' => 'Users', 'action' => 'login'],
            'unauthorized' => ['controller' => 'Dashboard', 'action' => 'index'],
        ],
    ],
];

Session Timeout and Redirect

When a user's session expires while using the Authorization Manager, they will be redirected to the login page with a redirect parameter containing the original URL.

To handle the redirect in your login controller, add this code after successful authentication:

// In your UsersController login action, after successful authentication:
public function login()
{
    $result = $this->Authentication->getResult();

    if ($result->isValid()) {
        // Check if there's a redirect parameter
        $redirect = $this->request->getQuery('redirect');

        if ($redirect) {
            // Redirect back to the original URL
            return $this->redirect($redirect);
        }

        // Default redirect
        $target = $this->Authentication->getLoginRedirect() ?? '/dashboard';
        return $this->redirect($target);
    }

    if ($this->request->is('post') && !$result->isValid()) {
        $this->Flash->error(__('Invalid username or password'));
    }
}

This ensures users are returned to the Authorization Manager page they were viewing after logging in.

Internationalization (i18n)

The plugin comes with Spanish (es_ES) and Galician (gl_ES) translations out of the box.

To change the language, add to your config/bootstrap.php:

use Cake\I18n\I18n;

// Set Spanish (default)
I18n::setLocale('es_ES');

// Or Galician
I18n::setLocale('gl_ES');

// Or English
I18n::setLocale('en_US');

To add your own translation:

Create resources/locales/{locale}/acl_manager.po in your app
Copy entries from vendor/mgomezbuceta/cakephp-aclmanager/resources/locales/es_ES/acl_manager.po
Translate the msgstr values
Run bin/cake i18n extract --plugin AclManager to update

Other Configuration Options

In your config/bootstrap.php:

use Cake\Core\Configure;

// Actions to ignore during resource scan
Configure::write('AclManager.ignoreActions', [
    'isAuthorized',
    'beforeFilter',
    'initialize',
    'AclManager.*',      // Ignore plugin
    'DebugKit.*'         // Ignore DebugKit
]);

// Permission checking mode
Configure::write('AclManager.permissionMode', 'strict'); // or 'permissive'

// Enable permission caching
Configure::write('AclManager.cachePermissions', true);
Configure::write('AclManager.cacheDuration', '+1 hour');

// Default role for new users
Configure::write('AclManager.defaultRoleId', 2);

🛠️ Cambios recientes (Unreleased)

Pequeño resumen de cambios detectados el 2025-12-02:

Se ha añadido Utilities/* a ignoreActions para excluir utilidades del escaneo de recursos.
AuthorizationManagerComponent ahora utiliza 'App' como valor por defecto para el parámetro plugin cuando no está presente.
PermissionsTable y ResourcesTable: tipos de columna boolean correctamente definidos (allowed, active).
ResourceScannerService::getGroupedResources() filtra plugins, controladores y acciones según ignoreActions antes de devolver los recursos agrupados.
Plantillas de permisos (templates/Permissions/*) integran adminRoleIds para evitar que roles administrativos sean eliminados desde la UI; el enlace "Clear All" ahora invoca la acción clearPermissions y el campo oculto plugin mantiene su valor real.
Archivos de traducción: limpieza de cadenas (ej. eliminación de la cadena "Deny").
Nueva política src/Policy/AclManagerPolicy.php que delega en PermissionService.
Se añadió la clase CSS .disabled-link en templates/layout/default.php para estilos de enlaces inactivos.

Nota: Se han detectado archivos en la carpeta .snapshots/. Estos archivos suelen ser generados por herramientas locales y no deberían comitearse. Se han eliminado del repositorio y añadida una entrada en .gitignore para evitar futuros commits accidentales.

🗄️ Database Schema

The plugin creates three tables:

roles — User roles: id, name, description, priority, active, created, modified
permissions — Role permissions: id, role_id, controller, action, plugin, allowed, created, modified
resources — Available resources (auto-discovered): id, controller, action, plugin, description, active, created, modified

🔌 Component Usage

// Load the component
$this->loadComponent('AclManager.AuthorizationManager');

// Check if user is authorized
$allowed = $this->AuthorizationManager->isAuthorized($user);

// Check specific permission
$allowed = $this->AuthorizationManager->checkPermission(
    $roleId,
    'Articles',
    'edit',
    'Blog' // plugin name (optional)
);

// Clear permission cache
$this->AuthorizationManager->clearCache();

// Handle unauthorized access
return $this->AuthorizationManager->handleUnauthorized();

🎯 Service Layer

use AclManager\Service\PermissionService;
use AclManager\Service\ResourceScannerService;

// Permission management
$permissionService = new PermissionService();

// Grant permission
$permissionService->grant($roleId, 'Articles', 'edit');

// Deny permission
$permissionService->deny($roleId, 'Articles', 'delete');

// Get permission matrix
$matrix = $permissionService->getPermissionMatrix($roleId);

// Copy permissions between roles
$permissionService->copyPermissions($sourceRoleId, $targetRoleId);

// Resource scanning
$scannerService = new ResourceScannerService();
$stats = $scannerService->scanAndSync();

// Get grouped resources
$resources = $scannerService->getGroupedResources();

🐛 Troubleshooting

No resources showing?

Visit /authorization-manager and click "Sync Resources"

Permission changes not taking effect?

// Clear cache
Configure::write('AclManager.cachePermissions', false);
// Or clear specific cache
$this->AuthorizationManager->clearCache();

Getting "access denied" after setup?

Make sure your User has a role_id assigned
Verify permissions are granted for that role
Check isAuthorized() is properly implemented

🔄 Migration from v2.x

⚠️ BREAKING CHANGE: Version 3.0 uses Authorization plugin instead of deprecated ACL.

Migration Steps

Backup your data

CREATE TABLE backup_aros_acos AS SELECT * FROM aros_acos;

Update composer.json

composer remove cakephp/acl
composer require cakephp/authorization
composer update mgomezbuceta/cakephp-aclmanager

Run new migrations

bin/cake migrations migrate -p AclManager

Update routes

Old: /acl-manager
New: /authorization-manager

Update component

// Old
$this->loadComponent('AclManager.AclManager');

// New
$this->loadComponent('AclManager.AuthorizationManager');

Rebuild permissions

Create new roles matching your old ARO structure
Use "Sync Resources" to discover controllers
Manually assign permissions (old ACL data cannot be migrated)

🏗️ Architecture

┌─────────────────────────────────────────┐
│      PermissionsController               │
│      (Web Interface)                     │
└──────────────┬──────────────────────────┘
               │
      ┌────────┴────────┐
      │                 │
┌─────▼──────────┐ ┌───▼──────────────────┐
│ Permission     │ │ ResourceScanner      │
│ Service        │ │ Service              │
│                │ │                      │
│ • Check Auth   │ │ • Scan Controllers   │
│ • Grant/Deny   │ │ • Sync Resources     │
│ • Copy Perms   │ │ • Auto-Discovery     │
└────────────────┘ └──────────────────────┘
        │                     │
        └──────────┬──────────┘
                   │
      ┌────────────▼─────────────┐
      │  Database Tables          │
      │  • roles                  │
      │  • permissions            │
      │  • resources              │
      └───────────────────────────┘
```text

---

## 🤝 Contributing

Contributions are welcome!

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (`git checkout -b feature/amazing-feature`)
3. 💻 Write clean, documented code following PSR-12
4. ✅ Add tests for new functionality
5. 📝 Commit your changes (`git commit -m 'Add amazing feature'`)
6. 🚀 Push to the branch (`git push origin feature/amazing-feature`)
7. 🎉 Open a Pull Request

---

## 📄 License

This project is licensed under the **MIT License** - see [LICENSE.md](LICENSE.md) for details.

```text
Copyright (c) 2025 Marcos Gómez Buceta
Copyright (c) 2016 Iván Amat

👨‍💻 Author

Marcos Gómez Buceta

🙏 Acknowledgments

This project evolved from the excellent ACL Manager foundation:

Iván Amat - Original CakePHP 4.x Acl Manager
Frédéric Massart (FMCorz) - Original CakePHP 2.x AclManager

Special thanks to the CakePHP community for their continuous support.

⭐ If you find this plugin useful, please give it a star! ⭐

Made with ❤️ for the CakePHP community

Report Bug • Request Feature

mgomezbuceta / cakephp-aclmanager

Maintainers

Details