Рекомендации по безопасности в приложениях на REST API

Выберите инструмент для разработки с AI-агентом:

используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Безопасность приложения зависит от корректной работы с токенами, проверки данных и защиты каналов связи. Ошибки на этих этапах приводят к утечкам информации или несанкционированному доступу.

Соблюдайте базовые правила защиты на всех этапах: при авторизации, обработке событий и хранении данных. Это поможет выстроить безопасный сценарий работы приложения.

Пошаговый сценарий безопасного запроса

Примите запрос от клиента и проверьте входящие параметры.
Проверьте токен на серверной стороне.
Убедитесь, что прав доступа scope достаточно для выполнения операции.
Выполните вызов REST API по протоколу HTTPS.
Обработайте лимиты и ошибки API.
Запишите результат в журнал без персональных данных.

Проверяйте входящие данные

Не считайте параметры от пользователя или внешних сервисов безопасными по умолчанию. Проверяйте значения до выполнения бизнес-логики и обращения к API.

Базовые правила:

валидируйте типы, диапазоны и обязательность полей
отклоняйте запросы с некорректным форматом данных
не используйте входящие значения в SQL-запросах, путях к файлам и системных командах без очистки
логируйте ошибки валидации без чувствительных данных

Пример проверки входного параметра:

$taskId = filter_input(INPUT_POST, 'TASK_ID', FILTER_VALIDATE_INT);
        
        if ($taskId === false || $taskId <= 0)
        {
            throw new \RuntimeException('Некорректный TASK_ID');
        }

Не доверяйте токенам из клиентского кода

Всегда проверяйте токен на серверной части приложения перед выполнением действий. Не доверяйте токену, полученному из клиентского кода.

Проверка помогает:

отсеять поддельные или устаревшие токены
снизить риск несанкционированного доступа к данным
централизовать контроль безопасности в одном месте

Минимальный чек-лист:

проводите проверку только на серверной части приложения
контролируйте срок жизни токена и обрабатывайте его истечение
убедитесь, что токен выдан для вашего приложения и Битрикс24
не выполняйте бизнес-логику, если проверка токена не пройдена
фиксируйте неуспешные проверки в журнале безопасности

Для облака и коробки используйте единый подход к обновлению токенов через сервер авторизации Битрикс24. Подробности читайте в обзоре различий облака и коробки.

Действуйте при компрометации токена

При подозрении на утечку токена действуйте немедленно по заранее подготовленному плану.

Остановите обработку запросов с подозрительным токеном.
Отзовите токен и выпустите новую пару.
Проверьте логи API на наличие аномальной активности.
Обновите секреты приложения, если они могли быть скомпрометированы.
Зафиксируйте инцидент и уведомите ответственных.

Удаление приложения делает все сохраненные токены невалидными. Подробнее читайте в статье Удаление приложений.

Для корректного завершения работы приложения зарегистрируйте обработчик OnAppUninstall. В этом событии данные авторизации уже неработоспособны, поэтому обязательно проверьте application_token. Такая проверка подтверждает, что вызов действительно пришел от Битрикс24.

Проверяйте application_token в событиях

Для каждого входящего события проверяйте поле application_token. Сверяйте его со значением, которое сохранено на сервере для соответствующего member_id, и обрабатывайте событие только при совпадении.

Если проверка application_token не пройдена, событие нужно отклонить и зафиксировать в журнале.

Рекомендуемый порядок:

сохраните application_token при установке приложения через OnAppInstall с привязкой к member_id
обновите сохраненное значение при событии OnAppUpdate, если Битрикс24 передал новый application_token
сравните значение токена для каждого входящего события до любой обработки данных
не запускайте обработчик события, если application_token не совпал или member_id не найден
логируйте факт отклонения без записи чувствительных данных

Алгоритм проверки входящего события:

Примите HTTP-запрос и проверьте структуру поля auth.
Проверьте наличие application_token.
Получите member_id из auth и найдите сохраненный application_token для этого member_id.
Сравните application_token из запроса с сохраненным значением.
При несовпадении верните отказ и не запускайте обработчик бизнес-логики.
При совпадении запустите обработчик и зафиксируйте результат обработки.

Результат успешной проверки:

{
          "status": "ok",
          "message": "event accepted"
        }

Отклонение события:

{
          "status": "error",
          "error": "invalid_application_token"
        }

Формат событий и состав поля auth описаны в разделе События.

Учитывайте, что поле auth не всегда содержит рабочие токены авторизации. В автоматических сценариях и в ряде событий данные авторизации могут отсутствовать или быть неактуальными.

Технические требования к приему событий и сетевому доступу смотрите в разделе Необходимые сетевые доступы.

Пример события с application_token:

{
          "event": "ONCRMLEADUPDATE",
          "data": {
            "FIELDS": {
              "ID": "123"
            }
          },
          "auth": {
            "access_token": "xxxx",
            "domain": "example.bitrix24.ru",
            "application_token": "51856fefc120afa4b628cc82d3935cce"
          }
        }

Не размещайте секреты во фронтенде

Не размещайте в клиентском коде секретные ключи вебхуков, OAuth-токены и другие чувствительные данные.

Безопасный подход: выполняйте все операции с токенами и ключами через серверную часть приложения. Сервер контролирует доступ и скрывает секретные данные.

Запрашивайте минимально необходимые scope

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

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

фиксируйте минимальный набор scope на этапе проектирования
не добавляйте права «про запас»
регулярно пересматривайте список и удаляйте неиспользуемые права

Проверяйте права каждого метода в его описании через блок scope.

Учитывайте лимиты REST API

При превышении лимита запросов облачный Битрикс24 возвращает статус 503 и код ошибки QUERY_LIMIT_EXCEEDED.

Чтобы снизить риск блокировок:

сократите количество запросов и используйте кеширование
используйте пакетные вызовы через batch
добавьте повторные попытки с задержкой при QUERY_LIMIT_EXCEEDED
контролируйте нагрузку на обработчики событий

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

Пример обработки QUERY_LIMIT_EXCEEDED:

$maxRetries = 3;
        $attempt = 0;
        
        while ($attempt < $maxRetries)
        {
            $response = $client->call($method, $payload);
            $status = $response['status'] ?? 200;
            $error = $response['error'] ?? null;
        
            if ($status === 503 && $error === 'QUERY_LIMIT_EXCEEDED')
            {
                usleep((2 ** $attempt) * 1000000);
                $attempt++;
                continue;
            }
        
            break;
        }

Подробнее

Используйте HTTPS

Передавайте токены и рабочие данные только по защищенному каналу HTTPS. Не отключайте проверку SSL-сертификата в рабочей среде.

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

используйте только https:// в endpoint и callback URL
проверяйте цепочку сертификата и имя хоста в HTTP-клиенте серверной части приложения
отключайте проверку сертификата только при изолированной локальной отладке

О требованиях к сетевому доступу читайте в разделе Необходимые сетевые доступы.

Минимизируйте хранение персональных данных

Храните только те данные, которые необходимы для работы приложения. Не собирайте информацию «на будущее».

Практические шаги:

определите сроки хранения и удаляйте устаревшие записи
ограничьте доступ к данным по ролям
не сохраняйте токены и персональные данные в открытых логах

Изолируйте приложения

Если на сервере работает несколько приложений, разделите их ресурсы:

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

Такой подход ограничивает зону риска и не позволяет одной уязвимости затронуть все приложения сразу.

Ведите журнал событий безопасности

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

Что логировать:

неуспешные проверки токенов и application_token
ошибки валидации входящих данных
срабатывания лимитов API и повторные попытки
отказы в доступе и ошибки авторизации

Что не нужно логировать:

access_token и refresh_token в открытом виде
персональные данные без необходимости
секреты приложения и служебные ключи

Пример безопасного логирования на серверной части приложения:

$maskedToken = substr($token, 0, 4) . '***';
        $b24Domain = $domain ?? '-';
        
        error_log(sprintf(
            'AUTH_FAIL app=%s b24=%s token=%s ip=%s',
            $appId,
            $b24Domain,
            $maskedToken,
            $_SERVER['REMOTE_ADDR'] ?? '-'
        ));

Приоритет мер безопасности

Обязательно

проверка входящих данных
валидация токенов и application_token
использование HTTPS
запрет на хранение секретов во фронтенде

Дополнительно

автоматические проверки требований безопасности в CI/CD
расширенная аналитика инцидентов и отчетность для команды

Анти-паттерны

Избегайте следующих решений:

передача webhook-ключей во фронтенд
отключение проверки SSL-сертификата в продакшене
тяжелая синхронная логика в обработчиках событий без очереди
использование общей базы данных и секретов для разных приложений
хранение application_token на клиентской стороне
изменение данных в обработчике события, которое снова вызывает это же событие

Чек-лист перед релизом

Перед публикацией приложения проверьте следующие моменты:

выполнены требования из разделов Обязательно и Рекомендуется по всем тестовым сценариям
сценарий компрометации токена отработан минимум один раз в тестовой среде
в логах тестового прогона нет access_token, refresh_token и персональных данных
очередь обработки событий включена, и обработчик корректно работает при пиковых входящих событиях

Соблюдение этих правил снижает риск утечек и повышает стабильность интеграции.

Продолжите изучение

Сетевые доступы

Обзор

Рекомендации по безопасности в приложениях на REST API

Пошаговый сценарий безопасного запросаПошаговый сценарий безопасного запроса

Проверяйте входящие данныеПроверяйте входящие данные

Не доверяйте токенам из клиентского кодаНе доверяйте токенам из клиентского кода

Действуйте при компрометации токенаДействуйте при компрометации токена

Проверяйте application_token в событияхПроверяйте application_token в событиях

Не размещайте секреты во фронтендеНе размещайте секреты во фронтенде

Запрашивайте минимально необходимые scopeЗапрашивайте минимально необходимые scope

Учитывайте лимиты REST APIУчитывайте лимиты REST API

Используйте HTTPSИспользуйте HTTPS

Минимизируйте хранение персональных данныхМинимизируйте хранение персональных данных

Изолируйте приложенияИзолируйте приложения

Ведите журнал событий безопасностиВедите журнал событий безопасности

Приоритет мер безопасностиПриоритет мер безопасности

ОбязательноОбязательно

РекомендуетсяРекомендуется

ДополнительноДополнительно

Анти-паттерныАнти-паттерны

Чек-лист перед релизомЧек-лист перед релизом

Продолжите изучениеПродолжите изучение