Безопасность

Настройки безопасности роута задаются в RouteConfig::SECURITY. Ключи перечислены в SecurityConfig.

Авторизация

Используйте константы SecurityConfig::LOGIN, SecurityConfig::TOKEN, SecurityConfig::TOKEN_ACCESS, SecurityConfig::TOKEN_REFRESH. auth принимает login для Basic или token для Bearer. Тип токена применяется при auth => token: access или refresh, по умолчанию — access.

Без auth запрос выполняется без авторизации API, независимо от сессии сайта. Неизвестное строковое значение auth возвращает AUTH_INVALID (HTTP 401).

Логин и пароль

// Basic-авторизация пользователя Битрикса
RouteConfig::SECURITY => [
    SecurityConfig::AUTH => SecurityConfig::LOGIN,
],

Access-токен

// Bearer-авторизация по токену доступа
RouteConfig::SECURITY => [
    SecurityConfig::AUTH => SecurityConfig::TOKEN,
    SecurityConfig::TOKEN_TYPE => SecurityConfig::TOKEN_ACCESS,
],

Refresh-токен

// Bearer-авторизация по токену обновления
RouteConfig::SECURITY => [
    SecurityConfig::AUTH => SecurityConfig::TOKEN,
    SecurityConfig::TOKEN_TYPE => SecurityConfig::TOKEN_REFRESH,
],

Для обоих типов Bearer проверяется привязка к клиенту. При несовпадении возвращается AUTH_INVALID (HTTP 401). Токены, выпущенные вручную, можно использовать в другом приложении.

Группы

В SecurityConfig::GROUP задаются списки символьных кодов групп, а не числовых ID:

В whitelist достаточно совпадения хотя бы с одной группой пользователя. Совпадение хотя бы с одной группой из blacklist запрещает доступ. Для обычных групп используется STRING_ID; регистр кодов не учитывается. Пустой список не вводит ограничение. Запрет blacklist имеет приоритет над whitelist.

RouteConfig::SECURITY => [
    SecurityConfig::AUTH => SecurityConfig::TOKEN,
    SecurityConfig::GROUP => [
        // Доступ для участников хотя бы одной из групп
        SecurityConfig::WHITELIST => ['api_clients', 'partners'],
        // Запрет имеет приоритет над разрешением
        SecurityConfig::BLACKLIST => ['api_blocked'],
    ],
],

Системные группы

anonymous обозначает запрос без авторизации API; administrators — администраторов; everyone — группу «Все пользователи» авторизованного пользователя.

// Доступ по токену для группы «Все пользователи»
RouteConfig::SECURITY => [
    SecurityConfig::AUTH => SecurityConfig::TOKEN,
    SecurityConfig::GROUP => [
        SecurityConfig::WHITELIST => [
            AccessConfig::GROUP_CODE_EVERYONE,
        ],
    ],
],

Администраторы проходят проверку групп независимо от списков. Без авторизации API проверяются права группы AccessConfig::GROUP_CODE_ANONYMOUS.

Эти же списки фильтруют операции документации по группам пользователя, открывшего документацию. Кнопка Authorize задаёт данные API-запроса и не меняет видимый список операций.

IP-адреса

Для конкретного роута задайте SecurityConfig::IP внутри RouteConfig::SECURITY. Оба списка принимают массивы IPv4-, IPv6-адресов или подсетей CIDR:

use Native\Api\Config\Internals\RouteConfig;
use Native\Api\Config\Internals\SecurityConfig;

// Фрагмент конфигурации роута
RouteConfig::SECURITY => [
    SecurityConfig::IP => [
        SecurityConfig::WHITELIST => ['192.0.2.0/24', '2001:db8::/32'],
        SecurityConfig::BLACKLIST => ['192.0.2.50', '2001:db8::50'],
    ],
],

В этом примере разрешены две подсети, кроме двух явно запрещённых адресов. Blacklist проверяется первым. Непустой whitelist допускает только совпавшие адреса; отсутствующие или пустые списки не добавляют ограничений роута.

Запрос должен пройти и глобальные IP-списки, и списки роута. Разрешение на одном уровне не отменяет запрет на другом. Проверяется REMOTE_ADDR; заголовки X-Forwarded-For и Forwarded не используются. Исключения для администраторов по IP нет.

Проверка роута выполняется после onAfterRouting, между событиями onBeforeIpAccess и onAfterIpAccess, до авторизации и чтения кеша ответа, поэтому срабатывает и при готовом кеше. Штатный OPTIONS завершается до выбора роута и проверяет только глобальные IP-списки. После изменения карты очистите кеш модуля.

Before может изменить списки текущей проверки, After вызывается только при её успешном завершении. Примеры — в регистрации событий.

При отказе возвращается HTTP 403 с кодом IP_BLACKLIST или IP_WHITELIST. Эти же коды используются для глобальных ограничений. IP-списки ограничивают выполнение запроса; список операций Swagger по ним не фильтруется.

Остальные ограничения

Глобальные IP-ограничения, расписание и лимиты задаются в настройках безопасности. Доступ к данным проверяет контроллер.