ACL: role, zdroje a pravidla
Potřebujete řídit přístup podle rolí uživatelů a částí webu? Třeba kdo smí hlasovat v anketách, kdo komentovat a kdo spravovat články? Třída Nette\Security\Permission vám umožní sepsat tato pravidla přehledně na jednom místě, včetně dědičnosti rolí a zdrojů.
ACL (Access Control List) je autorizátor,
který je součástí Nette: když se zeptáte $user->isAllowed('poll', 'vote'), objekt $user projde
role uživatele, na každou se zeptá ACL a povolí, pokud to smí aspoň jedna z nich. Hodí se všude, kde rozhodují role a
názvy částí webu.
Role a zdroje
Práce s ACL spočívá v definici rolí, zdrojů a jednotlivých oprávnění. Přičemž role a zdroje umožňují vytvářet hierarchie. Na vysvětlenou si ukážeme příklad webové aplikace:
guest: nepřihlášený návštěvník, který může číst a procházet veřejnou část webu, tzn. číst články, komentáře a volit v anketáchregistered: přihlášený registrovaný uživatel, který navíc může komentovatadmin: může spravovat články, komentáře i ankety
Nadefinovali jsme si tedy určité role (guest, registered a admin) a zmínili zdroje
(article, comment, poll), ke kterým mohou uživatelé s nějakou rolí přistupovat nebo
provádět určité operace (view, vote, add, edit).
Vytvoříme instanci třídy Permission a nadefinujeme role. Lze přitom využít tzv. dědičnost rolí, která
zajistí, že např. uživatel s rolí administrátora (admin) může dělat i to, co obyčejný návštěvník
webu (a samozřejmě i více).
$acl = new Nette\Security\Permission;
$acl->addRole('guest');
$acl->addRole('registered', 'guest'); // 'registered' dědí od 'guest'
$acl->addRole('admin', 'registered'); // a od něj dědí 'admin'
Nyní nadefinujeme i seznam zdrojů, ke kterým mohou uživatelé přistupovat.
$acl->addResource('article');
$acl->addResource('comment');
$acl->addResource('poll');
I zdroje mohou používat dědičnost, bylo by možné například zadat
$acl->addResource('perex', 'article').
Pravidla
A teď to nejdůležitější. Nadefinujeme mezi nimi pravidla určující, kdo co může s čím dělat:
// nejprve nikdo nemůže dělat nic
// nechť guest může prohlížet články, komentáře i ankety
$acl->allow('guest', ['article', 'comment', 'poll'], 'view');
// a v anketách navíc i hlasovat
$acl->allow('guest', 'poll', 'vote');
// registrovaný dědí práva od guesta, dáme mu navíc právo komentovat
$acl->allow('registered', 'comment', 'add');
// administrátor může prohlížet a editovat cokoliv
$acl->allow('admin', $acl::All, ['view', 'edit', 'add']);
Co když chceme někomu zamezit k určitému zdroji přístup?
// administrátor nemůže editovat ankety, to by bylo nedemokratické
$acl->deny('admin', 'poll', 'edit');
Nyní, když máme vytvořený seznam pravidel, můžeme jednoduše klást autorizační dotazy:
// může guest prohlížet články?
$acl->isAllowed('guest', 'article', 'view'); // true
// může guest editovat články?
$acl->isAllowed('guest', 'article', 'edit'); // false
// může guest hlasovat v anketách?
$acl->isAllowed('guest', 'poll', 'vote'); // true
// může guest komentovat?
$acl->isAllowed('guest', 'comment', 'add'); // false
Totéž platí pro registrovaného uživatele, ten však může i komentovat:
$acl->isAllowed('registered', 'article', 'view'); // true
$acl->isAllowed('registered', 'comment', 'add'); // true
$acl->isAllowed('registered', 'comment', 'edit'); // false
Administrátor může editovat vše, kromě anket:
$acl->isAllowed('admin', 'poll', 'vote'); // true
$acl->isAllowed('admin', 'poll', 'edit'); // false
$acl->isAllowed('admin', 'comment', 'edit'); // true
V aplikaci se ale na ACL takhle přímo neptáte. Stačí zavolat $user->isAllowed('poll', 'vote') a objekt
$user se za vás zeptá ACL na všechny role přihlášeného uživatele.
Podmínky v pravidlech
Oprávnění mohou také být vyhodnocována dynamicky a můžeme rozhodnutí nechat na vlastním callbacku. Pravidlo pak
platí, jen když callback vrátí true:
$assertion = function (Permission $acl, ?string $role, ?string $resource, ?string $privilege): bool {
return /* ... */;
};
$acl->allow('registered', 'comment', null, $assertion);
Callback dostane roli a zdroj pravidla, ke kterému patří. Když se pravidlo uplatní díky dědičnosti, jsou to předci
toho, na co se ptáte. Na co se ptáte, prozradí metody getQueriedRole() a getQueriedResource():
$acl->addResource('perex', 'article');
$assertion = function (Permission $acl, ?string $role, ?string $resource, ?string $privilege): bool {
// pro dotaz isAllowed('registered', 'perex', 'view') dostane $role = 'guest' a $resource = 'article'
$queriedRole = $acl->getQueriedRole(); // 'registered'
$queriedResource = $acl->getQueriedResource(); // 'perex'
return /* ... */;
};
$acl->allow('guest', 'article', 'view', $assertion);
Jak ale třeba řešit situaci, kdy nestačí jen názvy rolí a zdrojů, ale chtěli bychom definovat, že třeba role
registered může editovat zdroj article, jen pokud je jeho autorem? Místo řetězců použijeme
objekty, role bude objekt Nette\Security\Role a zdroj
Nette\Security\Resource. Jejich metody
getRoleId() resp. getResourceId() budou vracet původní řetězce:
class Registered implements Nette\Security\Role
{
public $id;
public function getRoleId(): string
{
return 'registered';
}
}
class Article implements Nette\Security\Resource
{
public $authorId;
public function getResourceId(): string
{
return 'article';
}
}
A nyní vytvoříme pravidlo:
$assertion = function (Permission $acl, ?string $role, ?string $resource, ?string $privilege): bool {
$role = $acl->getQueriedRole(); // objekt Registered
$resource = $acl->getQueriedResource(); // objekt Article
return $role->id === $resource->authorId;
};
$acl->allow('registered', 'article', 'edit', $assertion);
A dotaz na ACL se provede předáním objektů:
$role = new Registered(/* ... */);
$article = new Article(/* ... */);
$acl->isAllowed($role, $article, 'edit');
Dědění od více rolí
Role může dědit od jiné role či od více rolí. Co se ale stane, pokud má jeden předek akci zakázanou a druhý povolenou? Jaká budou práva potomka? Určuje se to podle váhy role – poslední uvedená role v seznamu předků má největší váhu, první uvedená role tu nejmenší. Názornější to bude na příkladu:
$acl = new Nette\Security\Permission;
$acl->addRole('admin');
$acl->addRole('guest');
$acl->addResource('backend');
$acl->allow('admin', 'backend');
$acl->deny('guest', 'backend');
// případ A: role admin má menší váhu než role guest
$acl->addRole('john', ['admin', 'guest']);
$acl->isAllowed('john', 'backend'); // false
// případ B: role admin má větší váhu než guest
$acl->addRole('mary', ['guest', 'admin']);
$acl->isAllowed('mary', 'backend'); // true
Role a zdroje lze i odebírat (removeRole(), removeResource()), odebrat lze i pravidla
(removeAllow(), removeDeny()). Pole všech přímých rodičovských rolí vrací
getRoleParents(), zda od sebe dvě entity dědí, vrací roleInheritsFrom() a
resourceInheritsFrom(). Existenci role či zdroje ověří hasRole() a hasResource(),
seznam všech registrovaných rolí a zdrojů vrací getRoles() a getResources() a k odstranění
všech naráz slouží removeAllRoles() a removeAllResources().
Přidání jako služby
Nejjednodušší je zapsat role, zdroje i pravidla do konfigurace. Pokud chcete ACL sestavit v PHP, napíšete si na něj továrnu:
namespace App\Model;
use Nette;
class AuthorizatorFactory
{
public static function create(): Nette\Security\Permission
{
$acl = new Nette\Security\Permission;
$acl->addRole(/* ... */);
$acl->addResource(/* ... */);
$acl->allow(/* ... */);
return $acl;
}
}
A přidáte ji do konfigurace. Vytvořené ACL pak objekt $user používá jako autorizátor:
services:
- App\Model\AuthorizatorFactory::create
V presenterech pak můžete ověřit oprávnění například v metodě startup():
protected function startup()
{
parent::startup();
if (!$this->getUser()->isAllowed('backend')) {
$this->error('Forbidden', 403);
}
}