☰
WORDPRESS / PRACTICE

Захист кастомних REST API endpoint у WordPress: permission_callback, права та валідація

Захист кастомних REST API endpoint у WordPress: permission_callback, права та валідація

Кастомний 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.

← Усі матеріали WordPress