О чем вообще речь?

Модули A1/A2/Acl предназначены для управления правами доступа пользователей. Дистрибутив Kohana v2.3 предоставляет нам только модуль Auth, который позволит контролировать минимальные доступные действия – регистрация, вход (login) и выход (logout). Но ведь помимо этого пользователь взаимодействует с различными объектами (ресурсами) сайта, и эти взаимодействия должны быть каким-то образом регламентированы. Самый простой пример – блог. Гости должны иметь возможность читать записи, авторизованные пользователи также могут комментировать, а администратор (владелец блога) – создавать записи и редактировать комментарии.

Подготовка к работе

Для ветки 2.3.x модули расположены здесь. Нас интересуют модули A1, A2 и Acl, а также демка с примером возможностей модулей A2 и Acl (она называется a2-acl-demo). Просто подкладываем их в папку MODPATH и добавляем в список модулей в config.php. Если запустить метод db контроллера a2demo (http://localhost/a2demo/db), то мы увидим минимально необходимую схему БД для дальнейшей работы с демо-модулем:

CREATE TABLE IF NOT EXISTS `users` (
		  `id` int(12) unsigned NOT NULL auto_increment,
		  `username` varchar(32) NOT NULL default '',
		  `password` char(50) NOT NULL,
		  `token` varchar(32) default NULL,
		  `logins` int(10) unsigned NOT NULL default '0',
		  `last_login` int(10) unsigned default NULL,
		  `role` enum('user','admin') NOT NULL,
		  PRIMARY KEY  (`id`),
		  UNIQUE KEY `uniq_username` (`username`)
		) ENGINE=InnoDB  DEFAULT CHARSET=utf8;
 
		CREATE TABLE IF NOT EXISTS `blogs` (
		  `id` int(12) unsigned NOT NULL auto_increment,
		  `user_id` int(12) unsigned NOT NULL,
		  `text` text NOT NULL,
		  PRIMARY KEY  (`id`),
		  KEY `user_id` (`user_id`)
		) ENGINE=InnoDB  DEFAULT CHARSET=utf8;

Т.е. необходимо создать таблицу для пользователей (она несильно отличается от используемой в Auth) и таблицу для сохранения наших разделяемых ресурсов (т.е. записей блога). Естественно, для настоящего блога эта табличка уж очень неактуальна, но сейчас цель – показать принцип работы модулей. Сами таблицы можно не заполнять – демо-контроллер позволит нам зарегистрироваться и немного поработать над блогом.

Знакомство с демо-версией

Откроем http://localhost/a2demo/. Поскольку мы не представились системе, нам предлагают войти или зарегистрироваться.

Блок авторизации для гостя

Форма для регистрации

Что видит пользователь

А теперь пришло время разобраться, как это все работает.

Второй демо-контроллер, описывающий работу модуля Acl, я тут показывать не буду, т.к. он гораздо менее информативен. После прочтения данной статьи Вы можете проанализировать его самостоятельно.

A1: аутентификация

Если Вы знакомы с модулем Auth, то все здесь будет понятно. Библиотека A1 предоставляет базовые методы login(), logout() и get_user(). Все знакомо. Настройка библиотеки хранится в конфигурационном файле (его имя передается в конструктор, по умолчанию ‘a1‘). Там тоже все более-менее понятно, новым для нас будет ключ ‘columns‘:

/**
 * Table column names
 */
$config['columns']   = array(
	'username'	=> 'username',    //username
	'password'	=> 'password',    //password
	'token'    	=> 'token',  			//token
	'last_login'=> 'last_login',  //last login (optional)
	'logins'    => 'logins' 			//login count (optional)
);

Как понятно из названия, тут описываются имена столбцов в БД. Из обязательных только первые три (если не планируется использовать “запоминание” пользователей, то и ‘token‘ не нужен). Это нужно для совместимости со сторонними таблицами пользователей.

В модуле определена абстрактная модель A1_User, от которой необходимо будет наследовать модель для реальной таблицы пользователей (по аналогии с Auth, там была абстрактная модель Auth_User). Имя модели пользователя указывается в параметре ‘user_model‘ (по умолчанию конечно же ‘user‘).

Acl: списки управления доступом

Библиотека Acl пришла в Kohana из фреймворка Zend и предполагает работу с тремя базовыми терминами: роль, ресурс и действие. Например, в условии “редактирование администратором записи в блоге” ролью будет ‘admin‘, действием – ‘edit‘ (редактирование), а ресурсом – запись в блоге (‘blog‘). Термины абстрактны, т.е. под записью в блоге будет рассматриваться любая запись, независимо от условий ее создания (автор, дата и т.д.), а под ролью ‘admin‘ – любой пользователь с данной ролью. Данные три термина объединяются в правила, которые определяют порядок взаимодействия с ресурсами. При этом все, что не разрешено – запрещено.

Сперва объявляем известные нам роли и ресурсы:

// создаем объект Acl
$acl = new Acl;
// добавляем роли
$acl->add_role('guest'); // гость
$acl->add_role('user'); // пользователь
$acl->add_role('admin'); // администратор
// добавляем ресурсы
$acl->add_resource('blog'); // блог
$acl->add_resource('comment'); // комментарий

Правила добавляются с помощью методов allow() и deny() объекта Acl:

// изначально все запрещено
// писать необязательно, привел для примера
$acl->deny(NULL, NULL, NULL);
//  все могут читать все
$acl->allow(NULL, NULL, 'read');
// пользователь и админ могут писать комментарии
$acl->allow(array('user', 'admin'), 'comment', 'write');
// админ может писать в блог
$acl->allow('admin', 'blog', 'write');

В правилах сперва указывается роль (или массив ролей), затем ресурс (или ресурсы), потом – действие (действия). Вместо перечисления всех ролей/ресурсов/действий можно указать NULL (так мы дали права на чтение в примере выше). Есть еще и четвертый параметр, но о нем поговорим отдельно.

Поскольку по умолчанию все запрещено, мы идем по пути “добавляем все, что можно”. Другой вариант – можно разрешить все ($acl->allow(NULL, NULL, NULL)), а затем добавить запрещающие правила. Главный минус – потом можно легко об этом забыть и оставить дыры в защите.

Проверяем права доступа:

var_dump($acl->is_allowed('guest', 'blog', 'write')); // false
var_dump($acl->is_allowed('user', 'comment', 'write')); // true
var_dump($acl->is_allowed('admin', 'blog', 'write')); // true

Использование иерархии

Перечисление всех имеющихся ролей и ресурсов при добавлении правил может превратиться в весьма утомительное занятие. Поэтому библиотека предоставляет возможность построения иерархий с наследованием правил от предка к потомку. Давайте переделаем вышеописанный пример:

// создаем объект Acl
$acl = new Acl;
// добавляем роли
$acl->add_role('guest'); // гость
$acl->add_role('user', 'guest'); // пользователь
$acl->add_role('admin', 'user'); // администратор
// добавляем ресурсы
$acl->add_resource('text'); // абстрактный ресурс
$acl->add_resource('blog', 'text'); // блог
$acl->add_resource('comment', 'text'); // комментарий

Как видно, была построена иерархия ролей (гость -> пользователь -> админ) и ресурсов (текст -> блог и текст -> коммент). Теперь все правила, примененные для гостя, будут доступны и пользователю с админом, а правила для текста могут быть использованы блогом и комментарием. Соответственно так теперь будем добавлять правила:

//  все могут читать все
$acl->allow('guest', 'text', 'read');
// пользователь и админ могут писать комментарии
$acl->allow('user', 'comment', 'write');
// админ может писать в блог
$acl->allow('admin', 'blog', 'write');

Если в правиле указан предок, потомков можно убирать (наследование в чистом виде). В первом правиле я заменил NULL на ‘text‘ – результат тот же, но само правило более четкое. Например, если добавится новый ресурс ‘stats‘, который должен быть разрешен только администраторам, общее правило с NULL позволит любому пользователю получить доступ. В общем, не ленитесь уточнять правила, чтобы потом после разрастания проекта это где-нибудь не аукнулось.

Проверка объектов

До этого мы говорили про абстрактные ресурсы и роли (в виде строк). Однако библиотека поддерживает передачу объектов, например можно использовать что-то вроде $acl->is_allowed($user, 'comment', 'write'); В этом случае объект $user (в данном случае имелся в виду экземпляр ORM-модели User_Model) должен реализовывать интерфейс Acl_Role_Interface, что заключается в наличии метода get_role_id():

class User_Model extends A1_User_Model implements Acl_Role_Interface {
 
	public function get_role_id()
	{// мы должны вернуть значение роли
		return $this->role;
	}

В данном случае возвращается значение поля role, т.к. оно присутствует в реализации библиотеки A1. Если говорить про Auth, там пришлось бы возвращать массив ролей из таблицы roles. Аналогично можно передавать ресурсы, только для них интерфейс называется Acl_Resource_Interface, а необходимый метод – get_resource_id().

class Blog_Model extends ORM implements Acl_Resource_Interface {
 
	public function get_resource_id()
	{
		return 'blog';
	}
}

Assertions

Казалось бы, зачем нам все эти сложности с передачей объектов, если правила Acl поддерживают только абстрактные строки? И вот тут на сцену выходят т.н. assertions (что-то вроде триггеров, дальше я буду использовать именно такой термин). Данные триггеры позволяют совершать дополнительные проверки с полученными объектами. Вот как реализовывается разрешение редактирования собственных комментов пользователем:

$acl->allow('user','comment','edit',array('Acl_Assert_Argument',array('id'=>'user_id')));

В результате при проверке $acl->is_allowed($user, $comment, 'edit') будет выполнена проверка на равенство $user->id и $comment->user_id (т.е. на принадлежность комментария текущему пользователю). Acl_Assert_Argument – это имеющийся в модуле Acl класс, позволяющий связывать между собой поля из моделей роли (в данном случае это модель User_Model, поле id) и ресурса (Comment_Model, поле user_id). Имена полей передаются в виде массива после имени класса. Можно использовать несколько связок, например так:

$acl->allow('user','comment','edit',array('Acl_Assert_Argument',array('id'=>'user_id', 'something_else' => 'other_field')));

Если все пары полей равны между собой, проверка вернет TRUE и доступ будет получен.

Конечно, это очень простой пример триггера, который не может решить всех проблем. Давайте попробуем реализовать простую проверку – создавать блог может только пользователь с количеством комментариев больше 100.

1. Каждый класс-триггер должен реализовывать интерфейс Acl_Assert_Interface. Это заключается в необходимости реализовать метод assert(), объявленный в интерфейсе следующим образом:

public function assert(Acl $acl, $role = null, $resource = null, $privilege = null);

Собственно говоря, данный метод как раз и вызывается при проверке правила. Таким образом, получим первый шаг на пути к созданию триггера:

class Acl_Assert_Comments implements Acl_Assert_Interface {
	public function assert(Acl $acl, $role = null, $resource = null, $privilege = null)
	{
	}
}

2.Если необходимо предварительно настроить триггер (в примере выше сперва должны были быть созданы соответствия пар полей из объектов роли и ресурса), используем конструктор. При создании правила, как мы помним, передается дополнительный параметр, который мы и будем обрабатывать:

class Acl_Assert_Comments implements Acl_Assert_Interface {
 
	protected $comments_required;
 
	public function __construct($arguments)
	{
		is_array($arguments) AND $arguments = $arguments[0];
		$this->comments_required = intval($arguments);
	}
 
	public function assert(Acl $acl, $role = null, $resource = null, $privilege = null)
	{
	}
}

Мы сохраняем переданное в конструктор значение (количество комментариев для ведения записей в блоге) в свойстве $comments_required. Далее в методе assert() оно будет использовано.
3. Осталось только реализовать сравнение количества комментов у пользователя с сохраненным значением:

class Acl_Assert_Comments implements Acl_Assert_Interface {
 
	protected $comments_required;
 
	public function __construct($arguments)
	{
		is_array($arguments) AND $arguments = $arguments[0];
		$this->comments_required = intval($arguments);
	}
 
	public function assert(Acl $acl, $role = null, $resource = null, $privilege = null)
	{
	    if ($role->comment_count < $this->comments_required) return FALSE;
 
		return TRUE;
	}
}

В данном примере поле comment_count присутствует в таблице users, так как я стараюсь избавиться от регулярного пересчета подобных статистических данных. Естественно, никто не мешает использовать что-то вроде $role->comments->count().

4. Вот и все, триггер создан и работает – можете проверять. Добавление правила будет выглядеть так:

	$acl->allow('user', 'blog', 'comment',  new Acl_Assert_Comments(100));

A2

По сути рассмотренные выше классы A1 и Acl между собой никак не свзяаны – один отвечает за “узнавание” пользователя, а второй “ставит его на место”. Для удобства работы с ними был создан класс-обертка A2. Он является потомком класса Acl и имеет все те же методы для работы с правилами. В качестве дополнения он агрегирует объект A1, что позволяет работать с текущим пользователем напрямую.
Какие методы нам предоставляет класс A2:
1. Разнообразные варианты создания объекта ( __construct(), factory() и instance() ). Все они принимают в качестве единственного параметра $config_name – имя файла конфигурации (об этом чуть ниже).
2. Методы для работы с объектом A1.
2.1. Метод logged_in() перенаправляет вызов к объекту A1, в результате получаем проверку залогиненности пользователя.
2.2. Метод get_user() таким же макаром возвращает сам объект модели пользователя (обычно это User_Model).
3. Метод allowed($resource = NULL, $privilige = NULL) проверяет, может ли текущий пользователь иметь возможность применить к ресурсу $resource действие $privilige. Таким образом, можно не передавать вручную в объект Acl пользователя, а использовать вот такую сокращенную запись.

Конфигурация

Самое интересное, что наверняка бросилось в глаза – наличие некого параметра $config_name в конструкторе. Да-да, можно не прописывать правила, роли и ресурсы в контроллере, а использовать заранее сохраненные настройки. Вот так вот будут выглядеть настройки, описанные нами выше:

$config['roles'] = array
(
	'user'			=>	'guest',
	'admin'			=>	'user'
);
 
$config['guest_role'] = 'guest';
 
$config['resources'] = array
(
	'text'			=>	NULL,
	'blog'			=>	'text',
	'comment'		=>	'text',
);
 
$config['rules'] = array
(
	'allow' => array
	(
		array('guest','text','read'),
		array('user', 'comment', 'write'),
		array('admin', 'blog', 'write'),
		array('user', 'blog', 'write', array('Acl_Assert_Comments', array(100))),
	),
);

Все довольно просто и понятно. Параметр $config['guest_role'] определяет имя роли, которая будет использоваться, если никто не залогился. Есть еще один дополнительный параметр, определяющий библиотеку для работы с аутентификацией (я говорил про A1, но ведь и Auth никто не отменял):

$config['a1'] = array('A1');

Если планируется использование другой библиотеки, то необходимо убедиться, что она реализует метод get_user() для получения текущего пользователя, а также использует шаблон Singleton – т.е. имеет статический метод instance(). В качестве параметра после имени библиотеки можно указать аргументы для передачи в метод instance(), обычно это имя конфигурации библиотеки. Сам объект будет сохранен в свойстве $a1 (оно объявлено как public).

Постскриптум

Вот собственно и все. В использовании A2 похожа на Acl, дополнительные возможности я указал. Самая неочевидная ошибка, на которую сам неоднократно напарывался – частенько забывал в моделях ролей и ресурсов реализовывать интерфейсы Acl_Role_Interface и Acl_Resource_Interface – они должны возвращать имя соответственно текущей роли (метод get_role_id()) или ресурса (get_resource_id()).

Для начала необходимо поработать над модулями, т.к. они были созданы под 3.0 со всеми сопутствующими препятствиями (иная структура папок, именование классов и еще несколько мелочей). Итоговый архив с небольшими доработками можно скачать тут. Модули разбиты на три папки, но в принципе их можно объединить в одну.

Настройка

Скопируйте модули и контроллер в соответствующие папки. В application/config/config.php не забудьте подключить модули. Кроме того, рекомендую закомментировать модуль Auth и проверить, нет ли в application/models моделей Auth и Blog (они присутствуют в модуле A2), т.к. они будет загружены вместо необходимым нам. Для работы прилагаемого демо-контроллера необходимы две таблицы, одна для пользователей, другая для контролируемого ресурса (блоги):

	CREATE TABLE IF NOT EXISTS `users` (
	  `id` int(12) UNSIGNED NOT NULL AUTO_INCREMENT,
	  `username` varchar(32) NOT NULL DEFAULT '',
	  `password` char(50) NOT NULL,
	  `logins` int(10) UNSIGNED NOT NULL DEFAULT '0',
	  `last_login` int(10) UNSIGNED DEFAULT NULL,
	  `role` enum('user','admin') NOT NULL,
	  PRIMARY KEY  (`id`),
	  UNIQUE KEY `uniq_username` (`username`)
	) ENGINE=InnoDB  DEFAULT CHARSET=utf8;
 
	CREATE TABLE IF NOT EXISTS `blogs` (
	  `id` int(12) UNSIGNED NOT NULL AUTO_INCREMENT,
	  `user_id` int(12) UNSIGNED NOT NULL,
	  `text` text NOT NULL,
	  PRIMARY KEY  (`id`),
	  KEY `user_id` (`user_id`)
	) ENGINE=InnoDB  DEFAULT CHARSET=utf8;

Поскольку таблица с пользователями у меня уже была, я просто добавил поле `role` и убрал в существующем поле `email` атрибут NOT NULL (данное поле в демо использоваться не будет). Если таблица `users` у вас тоже есть, не забудьте в файле modules/a1/config/a1.php привести настройки (метод хэширования, “соль” и т.д.) в соответствие с теми, что были в auth.php (он либо в application/config/, либо в modules/auth/config).

Вот собственно и все. Запускаем http://localhost/a2demo/ и видим предложение представиться/зарегистрироваться, а также сообщение, что блогов нет. Сперва войдем на сайт под существующем логином или зарегистрируемся. Тут все более-менее похоже на модуль Auth, разве что в выводимой Profiler‘ом информации на удивление мало запросов, связанных с пользователем (как мы помним, Auth делал три запроса).

Управление объектами

Так для чего же нам нужны эти две дополнительные библиотеки? Если вы еще не знакомы с Zend_Acl, самое время немного почитать. В общих чертах, Acl (списки доступа) – это некий набор типовых правил (“разрешить то-то”/”запретить то-то”), применяемых к отдельным классам ресурсов (в нашем случае это блоги) для текущего пользователя (точнее, для имеющихся у пользователя ролей). Так, в конфигурационном файле a2.php приведены правила следующего вида:

$config['rules'] = array
(
	'allow' => array
	(
			// guest can read blog
		array('guest','blog','read'),
		...
	),
...
}

Первый параметр – роль, второй – класс ресурса, далее имя операции. Все это разрешается (т.к. ключ “allow“). Аналогично существуют правила для запрета операций. Кроме того, роли пользователей выполнены в виде иерархии Гость->Пользователь->Админ с наследованием правил. Еще одна возможность – использование утверждений (asserts). Это правила с добавлением условий их применения (таким образом реализована проверка владельца блога при редактировании). Все правила загружаются из файла, а не из БД, хорошо это или плохо – решать вам. Мне кажется, с разрастанием приложения могут возникнуть проблемы…

А что насчет A2? Дело в том, что нас не всегда устраивают разрешения для целого класса ресурсов. Для отдельных экземпляров объектов в A2 можно применить отдельные правила. Для этого вместо строкового названия ресурса можно использовать экземпляр конкретного ресурса (например, ORM::factory(‘blog’,1), т.е. блог с идентификатором 1).

Помимо настроек в конфигурационном файле мы можем редактировать правила прямо в демо-контроллере:

// разрешаем редактирование всех блогов админами
$this->a2->allow('admin', 'blog', 'edit', NULL);
// добавляем для пользователей право на удаление блога с id=1
$this->a2->allow('user', ORM::factory('blog', 1), 'delete', NULL);
// запрещаем чтение блогов ВСЕМ пользователям (правила наследуются)
$this->a2->deny('guest', 'blog', 'read', NULL);

Итог

Получилось несколько сумбурно, но, надеюсь, что основную мысль я до вас донес. В любом случае скоро нам придется попробовать применить данный модуль вместо тяжеловесного Auth. И если не выявится еще какой-либо более интересный модуль, мы будем использовать именно связку A1+A2.

PS. В настоящее время имеется полноценная и развивающаяся версия данного модуля на гитхабе для ветки 2.3.