Кейсы
Ограничение входящих REST-хуков по методам
Как ограничить входящий хук выбранными REST-методами внутри уже выданных скоупов.
У входящего хука права задаются скоупами. Но скоуп открывает не один метод, а целый набор возможностей. Для внешней интеграции это часто слишком широкий доступ.
Задача
Нужно было добавить дополнительный уровень ограничений для входящих REST-хуков: оставить штатные скоупы как базовые права, но сверху проверять конкретный REST-метод, который пытаются вызвать.
Разрешить хуку только нужные REST-методы
Входящий хук удобно передать внешнему сервису, скрипту или подрядчику. Он позволяет обращаться к REST API без отдельной авторизации пользователя.
Но в этой задаче внешней стороне был нужен не весь набор методов из выданного скоупа, а только несколько разрешённых вызовов. Например, прочитать нужные данные, но не иметь возможности выполнять другие действия в том же разделе.
Поэтому требовалась настройка на уровне методов: для одного хука разрешить один список, для другого — другой, а всё лишнее блокировать.
Скоупы дают слишком широкий доступ
Скоупы хорошо подходят для грубого разделения доступа: CRM, пользователи, задачи и другие крупные разделы. Но они не дают точной настройки вида «этому хуку можно только эти методы».
Если интеграция выполняет узкую задачу, широкий доступ выглядит избыточным. Чем меньше действий разрешено внешней системе, тем проще контролировать её работу и сопровождать доступ.
Проблема
Обычная настройка входящего хука не позволяет сузить доступ до отдельных REST-методов. Если скоуп выдан, вместе с ним становятся доступны все методы, которые в него входят.
Один скоуп открывает больше методов, чем нужно
На практике интеграции часто нужен небольшой сценарий: получить профиль, прочитать список сделок, передать результат или забрать данные для отчёта. Но вместе с нужным скоупом открываются и другие методы.
Из-за этого один технический доступ может оказаться сильнее, чем нужно для реальной задачи. Особенно если хук используется внешним сервисом, временным скриптом или подрядчиком.
URL хука нельзя считать безопасным секретом навсегда
URL входящего хука сам является ключом доступа. Он может попасть в конфиг, лог, историю команд, резервную копию или рабочую переписку.
Поэтому ограничение должно работать на стороне портала, до выполнения REST-метода. Контроль только на стороне внешней системы не решает проблему: если URL уже известен, он не должен уметь больше, чем ему разрешено.
Решение
Я сделал локальный модуль, который добавляет для входящих хуков белый список REST-методов. Если хук добавлен в настройки модуля, каждый его вызов проходит дополнительную проверку.
Белый список REST-методов для каждого хука
Для каждого хука задаётся список разрешённых методов. Если запрошенный метод есть в списке, запрос проходит дальше. Если метода нет — вызов останавливается.
Такой подход не заменяет штатные права. Скоуп по-прежнему определяет общий доступ, а модуль уточняет, какие методы внутри этого доступа действительно можно использовать.
Добавление хука через админку
Для управления сделана административная страница. В ней можно добавить входящий хук по URL, дать ему понятное название и сохранить правило для дальнейших проверок.
Модуль разбирает ссылку, определяет технические данные доступа и сохраняет правило. Полный секрет хука не нужно постоянно показывать в интерфейсе.
Настройка разрешённых методов
Для каждого хука можно включить или выключить ограничение и указать разрешённые методы. Список задаётся в простом виде: по одному методу в строке или через разделители.
Так администратору не нужно править файлы или держать отдельную матрицу прав. Новый метод можно добавить через интерфейс, а лишний — убрать из списка.
Проверка методов внутри batch
Отдельно обработаны пакетные REST-запросы. Через batch можно выполнить
несколько методов внутри одного обращения, поэтому проверять только сам факт пакетного
запроса недостаточно.
Модуль проверяет каждый метод внутри пакета. Если внутри есть запрещённый вызов, пакетный запрос блокируется целиком.
Без этой проверки ограничение можно было бы обойти, спрятав лишний метод внутри
batch-команды.
Хранение секрета и настроек правила
Полный секрет хука не показывается в административной части как обычная открытая строка. Для отображения используется маска, а для проверки — техническое значение, по которому модуль сопоставляет запрос с настроенным правилом.
В настройках хранятся активность правила, название, данные хука и список разрешённых методов. За счёт этого ограничения можно менять без правки файлов: добавить новый хук, отключить старый, поменять методы или временно снять ограничение.
Результат
Входящие хуки получили более точный контроль доступа: не только по скоупам, но и по конкретным REST-методам.
Запрещённый метод останавливается до выполнения
Если внешний сервис вызывает метод, которого нет в белом списке, модуль останавливает запрос и возвращает ошибку. Разрешённые методы продолжают работать как раньше.
Доступ стал точнее, чем штатные скоупы
Для внешней интеграции хук остаётся обычным REST-URL. Разрешённые методы работают без изменения сценария обмена данными.
Если внешний сервис пытается вызвать лишний метод, запрос блокируется. То же правило применяется к методам внутри пакетных запросов.
В итоге доступ стал аккуратнее: можно выдать хук под конкретную интеграцию и ограничить его реальными задачами, а не всем набором методов внутри выбранного скоупа.
Решение не требует править ядро и подходит для нескольких интеграций одновременно. Для каждого хука можно задать свой набор разрешённых методов и сопровождать эти правила через административную страницу.