Csrf — фильтр проверки CSRF-токена
Пространство имен: Bitrix\Main\Engine\ActionFilter
Модуль: main — подключать отдельно не нужно
Когда использовать
Класс Csrf — префильтр действия контроллера. Фильтр проверяет CSRF-токен текущей сессии и останавливает действие, если токен не передан или неверный. Класс финальный, наследовать его нельзя.
Контроллер включает Csrf в фильтры по умолчанию вместе с Authentication и HttpMethod. Если configureActions задает префильтры с HttpMethod для метода POST, но без Csrf, контроллер сам добавляет Csrf для POST-запроса.
Чтобы изменить имя параметра с токеном или отключить проверку, передайте в configureActions объект Csrf с нужными аргументами конструктора.
Подробнее о фильтре — в разделе «Фильтр CSRF-защиты» статьи Префильтры и постфильтры.
Как фильтр проверяет запрос
Фильтр работает, только когда область контроллера Controller::SCOPE_AJAX. Эту область контроллер получает в конструкторе, другую задает метод setScope. Если область контроллера SCOPE_REST или SCOPE_CLI, контроллер не подключает фильтр.
Перед действием фильтр вызывает функцию check_bitrix_sessid. Фильтр берет токен из параметра запроса с именем из tokenName или из заголовка X-Bitrix-Csrf-Token.
Если токен неверный, фильтр:
- Добавляет ошибку
Bitrix\Main\Errorс сообщениемInvalid csrf tokenи кодомinvalid_csrf. - Добавляет текущий токен в дополнительные данные ошибки с ключом
csrfи в заголовок ответаX-Bitrix-New-Csrf, еслиreturnNewравенtrue. - Возвращает
EventResultс типомEventResult::ERROR, и контроллер не выполняет действие.
Константы
| Константа | Значение | Описание |
|---|---|---|
ERROR_INVALID_CSRF |
invalid_csrf |
Код ошибки неверного токена |
HEADER_WITH_NEW_CSRF |
X-Bitrix-New-Csrf |
Заголовок ответа с текущим токеном |
Наследование
Класс наследует Base.
Реализация методов базового класса
| Метод | Особенность реализации |
|---|---|
__construct(bool $enabled = true, string $tokenName = 'sessid', bool $returnNew = true) |
Параметр enabled включает проверку, при false фильтр пропускает любой запрос. Параметр tokenName задает имя параметра запроса с токеном. Параметр returnNew включает передачу текущего токена в ошибке и заголовке ответа |
listAllowedScopes |
Возвращает только Controller::SCOPE_AJAX. Если область контроллера SCOPE_REST или SCOPE_CLI, контроллер не подключает фильтр |
Унаследованные методы
Методы className, bindAction, getAction, getErrors и getErrorByCode работают как в классе Base.
Примеры
Пример. Код подключает фильтр к действию save и запускает действие без токена. Контроллер работает в области ajax по умолчанию, поэтому подключает фильтр, не выполняет действие и возвращает ошибку фильтра:
<?php
use Bitrix\Main\Engine\ActionFilter\Csrf;
use Bitrix\Main\Engine\Controller;
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';
final class DemoUnitController extends Controller
{
public function configureActions()
{
return [
'save' => [
'prefilters' => [new Csrf()],
],
];
}
public function saveAction()
{
return ['saved' => true];
}
}
$controller = new DemoUnitController();
var_dump($controller->run('save', []));
foreach ($controller->getErrors() as $error)
{
echo $error->getCode() . PHP_EOL;
}
Код выведет NULL и invalid_csrf.