Кастомный REST API endpoint в WordPress позволяет получать или изменять данные через HTTP-запросы. Это удобно для JavaScript-интерфейсов, мобильных приложений и интеграций, однако каждый новый маршрут расширяет поверхность атаки.
Самая распространённая ошибка — зарегистрировать маршрут с callback, но не продумать, кто именно может его вызывать. Параметр permission_callback — не формальность, а место, где определяется политика доступа к endpoint. Далее разберём, как защитить маршрут, почему nonce не заменяет авторизацию и как проверить endpoint на типичные ошибки.
Почему permission_callback обязателен для защищённого endpoint
При регистрации маршрута WordPress получает callback, который выполняет действие, и permission_callback, определяющий, разрешён ли запрос. Если проверку доступа не добавить или реализовать неправильно, endpoint может позволить изменять данные любому, кто знает его URL.
Для административных, внутренних маршрутов и маршрутов, изменяющих состояние сайта, доступ нужно запрещать по умолчанию. Проверяйте не только факт входа пользователя, но и конкретное право, необходимое для операции.
- current_user_can() проверяет capability текущего пользователя.
- Возврат true разрешает выполнение callback.
- Возврат false создаёт стандартный ответ о запрете доступа.
- WP_Error позволяет вернуть собственный код ошибки, сообщение и HTTP-статус.
add_action('rest_api_init', function () {
register_rest_route('site/v1', '/settings', [
'methods' => WP_REST_Server::CREATABLE,
'callback' => 'site_update_settings',
'permission_callback' => function () {
if (current_user_can('manage_options')) {
return true;
}
return new WP_Error(
'rest_forbidden',
'Недостатньо прав для зміни налаштувань.',
['status' => 403]
);
},
]);
});
Проверяйте capability, а не только авторизацию
Проверка is_user_logged_in() отвечает лишь на вопрос, вошёл ли пользователь в систему. Она не показывает, имеет ли он право изменять настройки, удалять записи или просматривать конфиденциальные данные. Авторизованный редактор, автор или подписчик не должны автоматически получать права администратора.
Для каждой операции выбирайте минимально необходимую capability. Например, для редактирования собственных записей может подойти edit_post с передачей ID записи, для удаления — delete_post, а для общих настроек сайта — manage_options. Не используйте manage_options для всех endpoint без необходимости: это чрезмерно широкое право.
Если доступ зависит от конкретного ресурса, проверка должна учитывать его ID. Сначала получите и проверьте объект, а затем вызывайте current_user_can() с соответствующей capability.
- Для настроек сайта обычно требуется право manage_options.
- Для работы с записью используйте edit_post, publish_post или delete_post в зависимости от действия.
- Для собственных данных пользователя дополнительно сравнивайте ID владельца с ID текущего пользователя.
- Не полагайтесь на роль администратора как на единственный критерий: capability лучше соответствует модели прав WordPress.
function site_can_edit_item(WP_REST_Request $request) {
$item_id = absint($request['id']);
if (!$item_id || !get_post($item_id)) {
return new WP_Error(
'rest_item_not_found',
'Об’єкт не знайдено.',
['status' => 404]
);
}
if (!current_user_can('edit_post', $item_id)) {
return new WP_Error(
'rest_forbidden',
'Недостатньо прав.',
['status' => 403]
);
}
return true;
}
Nonce не заменяет авторизацию
Nonce в WordPress помогает защищаться от CSRF-атак: он подтверждает, что запрос, вероятно, сформирован разрешённым интерфейсом для пользователя. Но nonce не является паролем, ролью или самостоятельной проверкой права доступа.
Пользователь с недостаточными правами может иметь корректный nonce для своей сессии. Поэтому даже после проверки nonce endpoint должен проверять current_user_can(). И наоборот, для внешних интеграций с токеном или другим механизмом аутентификации не следует считать наличие nonce универсальной защитой.
Для запросов из административной части WordPress nonce может быть дополнительным уровнем проверки. Для REST API проверяйте его только тогда, когда этого действительно требуют ваш сценарий аутентификации и клиент. Основная логика разрешения должна оставаться в permission_callback и проверках самого ресурса.
- Nonce защищает от подделки запроса, но не определяет capability пользователя.
- Nonce имеет ограниченный срок действия, поэтому не подходит в качестве долгосрочного API-токена.
- Не передавайте секретные ключи или пароли в открытых параметрах URL.
- Для каждого механизма аутентификации отдельно определите, каким образом WordPress устанавливает текущего пользователя.
Публичные endpoint также требуют защиты
Некоторые маршруты действительно должны быть доступны без входа: например, endpoint для списка категорий или отправки данных из публичной формы. В таком случае доступ нужно разрешить явно через __return_true, а не оставлять permission_callback без внимания.
Открытый endpoint не означает, что его callback может доверять входным данным. Публичные маршруты часто становятся целями спама, перебора параметров, чрезмерного использования ресурсов и попыток получить поля, не предназначенные для клиента.
- Проверяйте тип, формат, длину и допустимые значения каждого параметра.
- Ограничивайте количество элементов в пагинации и максимальный размер запроса.
- Не возвращайте пароли, токены, внутренние метаданные и лишние поля.
- Для форм, поиска и ресурсоёмких операций предусмотрите rate limiting или дополнительную антиспам-защиту.
- Кешируйте безопасные публичные ответы, если это не создаёт риска утечки персональных данных.
register_rest_route('site/v1', '/categories', [
'methods' => WP_REST_Server::READABLE,
'callback' => 'site_get_categories',
'permission_callback' => '__return_true',
'args' => [
'per_page' => [
'default' => 10,
'sanitize_callback' => 'absint',
'validate_callback' => function ($value) {
return $value >= 1 && $value <= 50;
},
],
],
]);
Валидация и санитизация параметров
Данные из REST-запроса нельзя считать безопасными только потому, что их отправила ваша форма или JavaScript-клиент. Клиентский код можно обойти, сформировав запрос вручную.
Валидация отвечает на вопрос, допустимо ли значение. Санитизация приводит его к безопасному или ожидаемому формату. Для критически важных полей лучше сначала проверить данные, а не молча исправлять любое некорректное значение.
Параметры endpoint можно описать в аргументе args при вызове register_rest_route(). Это упрощает проверку типов, обязательности, формата и допустимых значений. Однако сложные правила, зависящие от текущего пользователя или базы данных, нужно проверять в permission_callback или callback.
- Для числовых ID используйте absint() и проверяйте, что объект существует.
- Для текста задавайте максимальную длину и очищайте значение соответствующей функцией.
- Для email применяйте проверку формата и не полагайтесь только на HTML-атрибут type="email".
- Для списков разрешённых значений проверяйте значение по whitelist.
- При сохранении используйте API WordPress, соответствующий типу данных, а не прямые SQL-запросы со склеенными параметрами.
function site_update_settings(WP_REST_Request $request) {
$title = $request->get_param('title');
if (!is_string($title) || mb_strlen($title) > 100) {
return new WP_Error(
'rest_invalid_param',
'Некоректний заголовок.',
['status' => 400]
);
}
$title = sanitize_text_field($title);
update_option('site_title', $title);
return new WP_REST_Response(
['updated' => true],
200
);
}
Не возвращайте лишние данные из callback
Безопасность endpoint зависит не только от того, кто может его вызвать, но и от того, что именно он возвращает. Возврат полного объекта пользователя, записи или результата внутреннего запроса может раскрыть email, служебные метаполя, идентификаторы и другую информацию.
Формируйте ответ из конкретного набора полей, необходимых клиенту. Для стандартных объектов WordPress используйте подготовленные REST-ответы или явно формируйте массив. В случае ошибки не показывайте трассировку, SQL, абсолютные пути к файлам и секретные значения.
- Определите контракт endpoint: какие поля принимаются и какие возвращаются.
- Используйте WP_REST_Response или массив с минимально необходимыми данными.
- Возвращайте понятные коды ошибок и соответствующие HTTP-статусы.
- Технические детали записывайте в логи на сервере, но не передавайте их в ответе клиенту.
return new WP_REST_Response([
'id' => $post->ID,
'title' => get_the_title($post),
'url' => get_permalink($post),
], 200);
Как проверить endpoint после добавления
Проверку нужно выполнять не только через собственный административный интерфейс. Сформируйте запросы без авторизации, от пользователя с недостаточными правами и от пользователя, которому доступ разрешён.
Для endpoint, изменяющего данные, дополнительно проверьте повторную отправку запроса, некорректные типы параметров, отсутствие обязательных полей и попытку обратиться к чужому ресурсу.
- Без авторизации защищённый маршрут должен возвращать 401 или 403 в зависимости от механизма аутентификации.
- Авторизованный пользователь без необходимой capability должен получить 403.
- Разрешённый пользователь должен пройти permission_callback и корректную валидацию.
- Неизвестный ID или ресурс должен возвращать 404, а не данные другого объекта.
- Некорректные параметры должны завершаться ошибкой 400 или стандартной ошибкой REST API.
- Проверьте, что callback не выполняет часть операции до завершения всех проверок.
curl -i -X POST \
'https://example.com/wp-json/site/v1/settings' \
-H 'Content-Type: application/json' \
--data '{"title":"Нове значення"}'
Типичные ошибки при защите REST API
Наиболее опасные проблемы часто возникают не из-за сложной уязвимости, а из-за предположения, что endpoint будет вызываться только вашим интерфейсом. REST-маршрут доступен через HTTP, поэтому его можно вызывать вручную, повторно или с неожиданными параметрами.
Защита должна быть реализована на сервере и не зависеть от скрытого URL, названия кнопки или проверок в JavaScript.
- Пропущенный permission_callback или безусловный возврат true для приватного маршрута.
- Проверка только is_user_logged_in() вместо capability.
- Использование nonce как замены авторизации.
- Доверие к данным из формы без серверной валидации.
- Проверка права на сам факт доступа, но не на конкретный post ID или user ID.
- Возврат полного объекта с приватными полями.
- Отсутствие ограничений для публичного поиска, импорта или отправки форм.
- Изменение данных до выполнения всех проверок и проверка результата уже после записи.
Частые вопросы
Можно ли использовать __return_true для любого REST API endpoint?
Только для действительно публичных маршрутов, доступ к которым не требует авторизации. Даже в этом случае нужно отдельно проверять параметры, ограничивать объём ответа и продумывать защиту от спама и чрезмерной частоты запросов.
Какой HTTP-статус возвращать пользователю без необходимых прав?
Обычно используется 403 Forbidden, когда пользователь известен, но не имеет достаточных прав. Для неавторизованного запроса конкретный ответ может зависеть от механизма аутентификации и логики WordPress.
Достаточно ли проверить capability в callback?
Лучше размещать общую проверку доступа в permission_callback, а проверку конкретного ресурса и параметров выполнять дополнительно перед операцией. Авторизация и валидация не должны зависеть только от клиентского кода.
Нужен ли nonce для REST API в WordPress?
Nonce может быть дополнительной защитой от CSRF в сценариях с пользовательской сессией, но он не заменяет permission_callback, проверку capability или другой механизм аутентификации.
Как понять, что endpoint защищён правильно?
Проверьте маршрут без авторизации, от пользователя с недостаточными правами и от разрешённого пользователя. Также протестируйте некорректные параметры, чужие ID, повторные запросы и данные, которые endpoint возвращает в ответе.
Вывод
Безопасный кастомный REST API endpoint начинается с чёткой модели доступа. Для приватных маршрутов используйте permission_callback и проверяйте capability, необходимую именно для этой операции. Для ресурсов с владельцем проверяйте не только роль пользователя, но и принадлежность конкретного объекта.
Nonce может дополнять защиту от CSRF, но не определяет права пользователя. Независимо от типа endpoint сервер должен валидировать входные данные, минимизировать ответ и корректно обрабатывать ошибки. После реализации обязательно проверьте маршрут с разными уровнями доступа — ожидаемый запрет должен быть 403, а не выполнение callback.