Правило защиты API

Как запретить обращаться к выбранным API-эндпоинтам напрямую (в обход вашего сайта).

Доступно только для режима защиты Антибот.

Функционал подключается по запросу. Если внутри Пользовательских правил в UI вкладка «Правила защиты» неактивна, напишите в поддержку — откроем её для вас.

Для каждого ресурса можно создать только одно Правило защиты API.

О правиле

Описание

Правило защиты API — правило, где вы указываете конкретные эндпоинты, к которым защита будет блокировать запросы, отправленные напрямую (в обход вашего сайта).

Подходит для эндпоинтов, которые:

  • используются фронтендом;

  • не предназначены для прямого вызова через curl, скрипты и другие внешние инструменты;

  • не являются публичным API для внешних клиентов и интеграций.

Пример: ваш интернет-магазин использует API /api/cart для добавления товаров в корзину. Когда пользователь нажимает кнопку «Добавить в корзину» на странице, браузер отправляет запрос к этому API. Если кто-то попытается напрямую вызвать /api/cart без предварительной работы с сайтом, защита заблокирует такой запрос.

Как работает

  1. Пользователь открывает браузер и отправляет запрос к вашему сайту.

  2. Запрос проходит через нашу систему защиты. Если он легитимный, защита передаёт его на ваш сервер.

  3. Сервер отправляет ответ.

  4. Ответ проходит через нашу систему защиты. Защита добавляет к ответу служебную cookie Servicepipe.

  5. Браузер получает ответ и сохраняет cookie. Эта cookie будет добавляться ко всем следующим запросам к вашему сайту.

  6. Когда пользователь обратится к URI-пути, который вы добавили в правило защиты API, система защиты проверит cookie Servicepipe в запросе:

    • Если нужной cookie нет, запрос будет заблокирован.

    • Если нужная cookie на месте, система сначала проверит, не поддельная ли она. Затем рассчитает, как давно данный пользователь последний раз обращался к сайту. Если разрешённое время доступа истекло, заблокирует запрос. Если не истекло, проверит его другими политиками фильтрации и, если запрос легитимный, пропустит на ваш сервер.

Чем отличается от обычных правил защиты

Правило защиты API — специальный тип правил внутри раздела Пользовательские правила. Оно создаётся рядом с обычными правилами защиты, но отличается логикой работы, настройками и порядком применения.

Правило защиты API Обычные правила защиты

Когда выбирать

Нужно защитить внутренние API-пути, которые должны вызываться только в рамках работы пользователя с сайтом

Нужно фильтровать запросы по условиям и применять к ним выбранные действия

Что можно настроить

URL-путь и время доступа (в течение какого периода с последнего посещения сайта пользователю разрешено обращаться к этому пути)

Условия:

  • параметры трафика (URI-путь, страна, ASN, query string, headers, cookies, метод запроса, User-Agent, IP-адрес, подсеть, SP hash и другие);

  • лимиты запросов (глобальный и на один IP);

  • зависимость работы правила от статуса DDoS-атаки.

Что делать запросом, совпадающим с условиями правила:

  • пропустить;

  • заблокировать;

  • выдать JS-челлендж;

  • выдать cookie-челлендж;

  • выдать CAPTCHA.

Для каждого из классов источника запроса (человек, вероятно человек, вероятно бот, бот) можно выбрать отдельное действие.

Что происходит с запросом

Запрос пропускается, если содержит действующую служебную cookie Servicepipe и разрешённое время доступа ещё не истекло. В остальных случаях запрос блокируется.

Если запрос подходит под условия, к нему применяется указанное действие: пропустить, заблокировать, выдать JS-челлендж, cookie-челлендж или CAPTCHA

Сколько правил можно создать

Одно, но в него можно добавить несколько API-путей

20, по запросу можем увеличить лимит

Как отображается в UI

Самое первое в списке правил, без номера

Ниже правила защиты API, с номером в общем списке

Какое место занимает в иерархии фильтрации

Наша защита фильтрует каждый запрос поэтапно: сначала с помощью одного механизма фильтрации, затем второго, третьего и так далее. В списке ниже вы увидите, на каком месте стоит Правило защиты API:

  1. Чёрный список.

  2. Белый список.

  3. Верифицированные боты.

  4. Обеление по URL или заголовку.

  5. Геоограничения.

  6. Лимиты запросов.

  7. Правило защиты API.

  8. Обычные правила защиты.

  9. Индивидуальные настройки защиты.

Если запрос подходит под условия нескольких механизмов фильтрации, применяется тот, который сработал первым. Например, белый список проверяется раньше правил защиты. Поэтому запрос с IP-адреса из белого списка будет пропущен на ресурс, даже если он обращается к эндпоинту, для которого настроено правило защиты API.

Рекомендации

  • Добавляйте в правило только те URL-пути, которые вызываются во время работы пользователя с сайтом и не должны вызываться напрямую.

  • Правило защиты API не подходит для публичного API, к которому должны напрямую обращаться мобильные приложения, внешние клиенты или интеграции. Для защиты такого API обратитесь в поддержку. Мы проанализируем его трафик, проведём обучение и настроим фильтрацию сами.

  • Для каждого ресурса можно создать только одно Правило защиты API. Если нужно защитить несколько API-путей, добавьте их в одно правило через + Или.

  • Не используйте правило вместо авторизации. Оно защищает API от прямых запросов в обход сайта, но не проверяет права пользователя внутри вашего ресурса.

  • Выбирайте время доступа с учётом поведения пользователей и сценариев работы вашего ресурса. Если пользователь может долго взаимодействовать с ресурсом после открытия страницы, установите большее значение, например 8 или 24 часа. Если API вызывается только сразу после открытия сайта, используйте меньшее время, например 30 минут или 1 час.

Настройка

Открыть «Правила защиты»

Перейдите в раздел Защита приложений → Ресурсы. Напротив ресурса, для которого нужно настроить правило, нажмите на многоточие (…) и выберите Пользовательские правила. Откроется раздел, где вы найдёте вкладку Правила защиты.

Переход к списку ресурсов
Переход к разделу с правилами

Создать правило защиты API

Перед созданием правила убедитесь, что между сайтом и API настроена передача служебной cookie Servicepipe. Это очень важно: иначе правило будет просто блокировать любые запросы к указанным URI-путям, ведь они пришли без нужной cookie.

Если ваши сайт и API находятся:

  • На одном домене (например domain.ru и domain.ru/api) — настройте передачу cookie на своей стороне по инструкции ниже.

  • На разных поддоменах одного домена (например site.domain.ru и api.domain.ru) — сделайте следующее:

    1. Напишите в поддержку, чтобы мы настроили передачу cookie на нашей стороне.

    2. Настройте передачу cookie на своей стороне по инструкции ниже.

  • На разных доменах (например domain.com и api.domain.ru) — передать служебную cookie между такими ресурсами невозможно. Правило защиты API настроить не получится.

Инструкция по настройке передачи cookie

1. Настройте CORS на стороне API.

Перейдите в файл конфигурации site.conf, где обрабатывается домен, и добавьте следующие заголовки.

Набор заголовков зависит от конфигурации вашего API. Возможно, их потребуется добавить только для определённых локаций ресурса.
Заголовок Что указать Пример

Access-Control-Allow-Origin

Конкретный домен сайта. Не используйте *, иначе браузер не будет отправлять cookie.

add_header 'Access-Control-Allow-Origin' 'https://site.domain.ru' always;

Access-Control-Allow-Credentials

Значение true для разрешения передачи cookie в запросах.

add_header 'Access-Control-Allow-Credentials' 'true' always;

Access-Control-Allow-Methods

Используемые методы API. (опционально)

add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';

Access-Control-Allow-Headers

Используемые заголовки API. (опционально)

add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization, X-API-Key, X-CSRF-Token';

2. Включите передачу cookie на стороне сайта.

Найдите JS-код, который отправляет запросы к API, и добавьте передачу credentials.

Эти настройки нужны, чтобы после прохождения дополнительных проверок на стороне сайта браузер мог получить служебную cookie и передавать её в последующих запросах к API.

Для Fetch:

fetch('https://city.domain.ru', {
  method: 'GET',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
  },
});

Для XMLHttpRequest:

const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://city.domain.ru', true);
xhr.withCredentials = true;
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.send();

  1. Нажмите + Создать правило защиты и выберите Правило защиты API. Откроется окно для создания правила, остальные шаги выполняйте в нём.

    Если при клике на + Создать правило защиты не появляется выпадающее меню, значит, у вас уже создано одно правило защиты API. Создать второе нельзя. Но вы можете отредактировать первое и добавить в него новые URI-пути.
    Кнопка создания нового правила
    Создание нового правила

  2. Укажите Защищаемые URL-пути.

    Сначала выберите оператор сравнения:

    • = (равно) — правило сработает только для указанного пути. Например, при = /api/search, система будет проверять только запросы к /api/search.

    • *... (начинается с) — правило сработает для указанного пути и всех вложенных. Например, при *... /api/cart, система будет проверять запросы к /api/cart, /api/cart/add, /api/cart/remove и другим путям с таким началом.

    Затем укажите путь. Он должен начинаться с /.

    Чтобы добавить сразу несколько URL-путей, используйте кнопку + Или. Правило будет защищать запросы к любому из этих путей.

    Пример заполнения:

    /api/search

    /api/items ИЛИ /api/cart

  3. Настройте Разрешённое время доступа.

    Когда придёт запрос к любому из указанных на шаге 2 URI-путей, система проверит, как давно пользователь последний раз посещал сайт. Если разрешённое время доступа истекло, заблокирует запрос.

    Можно выбрать готовое значение из списка или задать произвольное время в минутах. Максимальное значение — 1440 минут (24 часа).

  4. Нажмите Создать.

    Созданное правило появится в общем списке на вкладке Правила защиты. Оно всегда будет стоять в самом верху и у него не будет номера в столбце №.

    Чтобы правило начало работать, нажмите на переключатель в столбце Включено.

    Переключатель для включения и отключения правила

Пример настройки

Задача: защитить API поиска и карточек товаров от прямых вызовов в обход сайта.

Настройки правила:

  • Защищаемые URL-пути — *... /api/search ИЛИ *... /api/item.

  • Разрешённое время доступа к API после последнего посещения сайта — 8 часов.

В течение 8 часов после последнего посещения вашего сайта пользователь сможет обращаться к /api/search, /api/item и их вложенным путям — при соблюдении трёх условий:

  • запрос делается из того же браузера, откуда посещался сайт;

  • в течение этих 8 часов пользователь не чистил cookie для вашего сайта;

  • пользователь сделал запрос не в режиме инкогнито.

Управление

В разделе Пользовательские правила → Правила защиты можно управлять правилом прямо из списка:

  • Включить/выключить: используйте переключатель в столбце Включено, чтобы временно включить или выключить правило.

  • Редактировать: нажмите на многоточие (…) в конце строки и выберите Редактировать. Здесь вы сможете изменить любые параметры правила.

  • Удалить: нажмите на многоточие (…), выберите Удалить и подтвердите действие. После удаления правила в меню создания снова появится возможность выбрать Правило защиты API.

Действия над правилами