У коробочного Битрикс24 есть маленькая тайна, которую знают не только лишь все, а те, кто хоть раз писал для него локальное приложение. Коробка может стоять у вас в серверной, на вашем железе, за вашим межсетевым экраном, под присмотром вашего администратора. Она ваша целиком, совершенно независимая от Битрикс. Но не совсем. Каждый раз, когда пользователь открывает локальное приложение, коробка вежливо стучится в облако, на oauth.bitrix.info, и запрашивает токен. И может, кстати, и не получить. Вот такая независимость и, даже я бы сказал, суверенитет!

Да, так всё устроено. Сервер авторизации живёт в инфре Битрикс, коробка ходит к нему за токенами, проверяет их там же, обновляет там же и через него же рассылает REST-события. Пока сеть работает, этого никто не замечает. Но в какой-то момент этой песни вам могут наступить на горло. Не специально, конечно. Ну, или да.

Есть проблема, нужно решение. Поэтому я написал PocketAuth24, который почти такой же молодец, как официальный сервер авторизации, но маленький и живёт рядом с коробкой. Лицензия MIT, код на GitHub: github.com/serg-vostrikov-bitrix/pocketauth24. Ниже о том, в чём от него польза, как он устроен, где он ещё сыроват и какие неожиданные сценарии из него вылезли.

Хочу подчеркнуть: PocketAuth24 — независимый проект. Он не связан с Битрикс24, не одобрен и не сертифицирован компанией. Слова «замена облачного сервера авторизации» описывают, что делает программа, а не отношения с вендором.

С чего всё началось: дискуссия в чате разработчиков

Недавно облачный сервер авторизации Битрикс24 работал нестабильно, и часть порталов на какое-то время до него не могла достучаться. Что именно там произошло, никто не знает. Задело не всех, но кого задело, тот прочувствовал: токены не приходят, приложения показывают заглушку вместо интерфейса, клиенты наезжают, всё пропало в очередной раз.

Вообще, такие инциденты случались и будут случаться — это нормально. Между конкретной коробкой (или даже облачным порталом) и сервером авторизации лежит интернет со всеми его маршрутизаторами, провайдерами и экскаваторами («экскаватор» — это результат опечатки в слове «РКН», которую допустил AI, поскольку весь текст он писал). Где-то теряется трафик, где-то отваливается маршрут, и приложение, которое пять минут назад исправно работало, превращается в прямоугольник с крутящимся колёсиком.

В чате разработчиков по этому поводу случилась очередная большая дискуссия. И поскольку именно в этом чате в большинстве сидят именно «коробочники», то главный аргумент звучал так: раз у вас коробка, значит, у вас есть коробочный API. Зачем вообще связываться с REST, если REST тянет за собой внешнюю инфраструктуру? Отвалится облако — отвалится всё.

Аргумент разумный. Но я с ним не до конца согласен.

Почему REST — хороший выбор даже для коробки

Во-первых, REST одинаковый для облака и для коробки. Решение, написанное на REST, не привязано к способу размещения портала: сегодня коробка, завтра облако, послезавтра снова коробка, потому что пришла служба безопасности. Код при этом остаётся тем же.

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

Но даже здесь, по-моему, правильнее другой путь. Добавьте в коробку свой модуль, который реализует на базе API ядра недостающий REST-метод. Бизнес-логика по-прежнему пишется на REST, просто в этой конкретной коробке метод, которого раньше не было, появился. Дальше локальное приложение — отдельный веб-сервис — обращается к коробке стандартным способом: с авторизацией, с правами пользователя, с проверкой токенов. Свои механизмы безопасности изобретать не нужно. А мы все понимаем (мы же понимаем, да?), что именно сейчас любую проблему в безопасности, которую может не заметить разработчик очередного альтернативного механизма вызова коробочного API из внешнего сервиса, очень быстро найдут и смогут эксплуатировать. Потому что AI. А стандартные механизмы давно отлажены и проверены тысячами порталов.

Осталась одна проблема: этот стандартный способ упирается в облачный сервер авторизации. Вот её PocketAuth24 и убирает.

Было и стало: куда коробка ходит за токенами
Было и стало: куда коробка ходит за токенами

Что же такое этот ваш PocketAuth24?

Это независимый сервис для самостоятельного размещения. Он отвечает на те же вызовы, которые коробочный портал иначе отправил бы на oauth.bitrix.info или oauth.bitrix24.tech. Один контейнер, одна база PostgreSQL 17, всё внутри вашей сети. Портал направляется на этот сервер тремя строками в командной PHP-строке в админке коробки — и дальше локальные приложения открываются, вызывают REST, обновляют токены и получают события, ни разу не выглянув в интернет.

Стек: Node.js 24, TypeScript в строгом режиме, Fastify 5, Drizzle, PostgreSQL 17, Docker Compose.

Что умеет сервер сегодня:

Область

Что происходит

Регистрация портала

Портал регистрируется сам при первом обращении. Пустят только тех, кто в списке разрешённых адресов (PORTAL_ALLOWLIST). Данные каждого портала хранятся отдельно.

Локальные приложения

Создаются, меняются и удаляются на портале как обычно. Сервер выдаёт client_id и client_secret и держит реестр. Удалили приложение — удалились все его токены.

Токены

rest.authorize выдаёт пару токенов для нужного пользователя, в том числе не администратора. rest.check проверяет токены. Область доступа — пересечение запрошенной и разрешённой приложению.

Обновление

/oauth/token/ с grant_type=refresh_token. Access-токен живёт 3600 секунд, refresh-токен — 180 дней, как в облаке.

События

rest.event.call: сервер сам доставляет каждое событие обработчику приложения, включая ONAPPINSTALL со свежими токенами.

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

Токены и секреты хранятся только в виде хешей. Строки запроса в логи не попадают.

Эксплуатация

Страница статуса, /health, JSON-логи, многопользовательская панель администратора (пока только чтение).

Страница статуса PocketAuth24: состояние сервиса и базы, порталы, локальные приложения, активные пары токенов и доставленные события. Страница статуса по адресу `/`. Показывает только агрегированные числа.
Страница статуса PocketAuth24: состояние сервиса и базы, порталы, локальные приложения, активные пары токенов и доставленные события. Страница статуса по адресу `/`. Показывает только агрегированные числа.

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

Как это работает внутри

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

Последовательность вызовов между порталом, PocketAuth24 и локальным приложением
Последовательность вызовов между порталом, PocketAuth24 и локальным приложением

Формы ответов и коды ошибок не выдуманы: они сверены контрактными тестами с трафиком, записанным между реальным порталом (модуль rest 26.1100) и настоящим oauth.bitrix.info. Всё может работать и в закрытой сети — регистрация, создание приложения, страница установки с токенами, REST от администратора и от обычного пользователя, ONAPPINSTALL, обновление токена, повторное обновление и удаление. Интернета нет, а REST API есть.

Отдельная история — доставка событий. В случае стандартного сервера авторизации Битрикс24 обработчики приложений вызываются со стороны ещё одного сервера в инфре Битрикс24 — сервера очередей. Вы можете в доке посмотреть их адреса (network-access). И когда эти вызовы до вас дойдут, и дойдут ли вообще, — от вас не очень зависит. Обычно доходят, но иногда... Как ни странно, если не доходят, то это обязательно именно в те редкие моменты, когда события были ну просто смертельно необходимы!

Портал отправляет все события одного хита одним пакетом и не повторяет его, если что-то пошло не так. PocketAuth24 сразу отвечает порталу, а события доставляет в фоне: одна попытка, тайм-аут 10 секунд, не больше 200 одновременных доставок в сумме и не больше 100 на один хост обработчика. Медленный обработчик может занять свои 100 мест, но не может задушить соседей.

Доставка событий: портал получает ответ сразу, события уходят обработчикам в фоне
Доставка событий: портал получает ответ сразу, события уходят обработчикам в фоне

Совет обработчикам такой же, как и для облака: отвечайте за секунду, кладите событие в свою очередь, а работайте потом. Во всяком случае, имея свой сервер для отправки событий, вам уже не придётся жаловаться на Битрикс24, если вдруг что-то упадёт или не доедет. Все карты у вас на руках — дерзайте!

Давайте поразмышляем, где всё это добро реально может пригодиться?

Сценарий первый для параноидальных клиентов: закрытый контур

С него всё и начиналось. Регулируемые отрасли, оборонка, банки, госсектор, любая компания, где служба безопасности смотрит на исходящий трафик, как таможенник на чемодан с двойным дном. Портал не может выходить в интернет, а значит, до сих пор у него было два варианта: отказаться от локальных приложений или пробить дыру наружу, которую потом придётся объяснять на каждом аудите.

PocketAuth24 даёт третий: поднять сервер авторизации в том же закрытом контуре. Образ собирается на машине с интернетом, переносится куда надо и запускается docker compose up -d. Дальше — три строки в командной PHP-строке портала:

\Bitrix\Main\Config\Option::set('rest', 'oauth_server', 'https://auth.corp.local');
\Bitrix\Main\Config\Option::delete('rest', ['name' => 'service_client_id']);
\Bitrix\Main\Config\Option::delete('rest', ['name' => 'service_client_secret']);

Портал сам зарегистрируется на новом сервере при следующем обращении. Локальные приложения, созданные раньше, придётся пересоздать, а жёстко прописанный в SDK адрес https://oauth.bitrix.info/oauth/token/ заменить на свой (или направить внутренний DNS на прокси с сертификатом внутреннего удостоверяющего центра). В общем, варианты понятные и простые.

Сценарий второй для продуманных разработчиков: тестовый стенд, который не ломает прод

Этот сценарий, по-моему, даже интереснее закрытого контура, потому что касается почти всех, кто разрабатывает на REST API под коробку (а я надеюсь, что таких станет больше теперь-то...)

Тестовый стенд обычно делают так: разворачивают ещё один экземпляр коробки на том же лицензионном ключе, часто из свежего бэкапа прода. Пока тестируют интерфейс, всё хорошо. Как только дело доходит до REST и локальных приложений, начинается ерунда. Прод и его копия ходят на один и тот же облачный сервер авторизации, с одним и тем же ключом, а в копии ещё и лежат служебные учётные данные прода, приехавшие из бэкапа. Сервер авторизации видит двух близнецов с одним паспортом, и у него, мягко говоря, довольно часто сносит крышу. URL приложений путаются, регистрации перезаписываются, и эксперимент на деве внезапно аукается на проде.

С PocketAuth24 у стенда свой сервер авторизации. Копия не регистрируется в облаке и ничего не знает о проде. Удаляете в копии служебные учётные данные, направляете её на отдельный экземпляр PocketAuth24, пересоздаёте локальные приложения — и получаете полностью независимый стенд. На нём можно отлаживать любые сценарии с REST, событиями, установкой приложений и обновлением токенов, будучи уверенным, что эксперименты на деве не долетят до прода.

Прод и тестовая копия на одном лицензионном ключе: было и стало
Прод и тестовая копия на одном лицензионном ключе: было и стало

Тот же приём работает для CI. Контейнер портала и PocketAuth24 поднимаются в одном стеке Compose, и сквозные тесты — установка приложения, ONAPPINSTALL, вызовы REST, обновление токенов — проходят без облака. Результат тестов больше не зависит от того, хорошо ли сегодня внешнему сервису.

Сценарий третий для недоверчивых клиентов: прод с интернетом, но без лишней зависимости

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

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

При этом интегратору, который обслуживает несколько коробочных клиентов, не нужен отдельный экземпляр на каждый портал: один PocketAuth24 держит несколько порталов, данные каждого хранятся отдельно, так что это тоже интересная возможность, над которой стоит поразмышлять.

Сценарий четвёртый, «волшебный», запланированный: страховочная сетка

Самый вкусный сценарий пока живёт в плане развития (issue #10), но анализ для него уже сделан.

Идея такая. PocketAuth24 работает не заменой, а прослойкой. В обычном режиме он честно пересылает все вызовы в официальный сервер авторизации Битрикс24 и только запоминает хеши того, что облако подтвердило: токены, учётные данные порталов и приложений. События при этом доставляет сам (потому что с ними новые токены приходят).

Как только облако перестаёт отвечать (тайм-аут, разрыв соединения, ошибка 5xx — несколько раз подряд), прослойка переключается и начинает выдавать токены сама. С точки зрения приложений ничего не происходит: они продолжают работать, токены продолжают приходить. Когда облако оживает, прослойка проверяет его несколько раз подряд, чтобы не прыгать туда-сюда при мигающей сети, и постепенно возвращается к официальным токенам. Локально выданные access-токены сами истекают за час, никакой отдельной процедуры «слива» не требуется.

Режим страховочной сетки: три состояния прослойки
Режим страховочной сетки: три состояния прослойки

Получается не альтернатива облаку, а контур защиты, который включается только в критические моменты, ненадолго, на время сетевых проблем. Важная оговорка из анализа: отказ облака — это молчание, а не отказ. Если облако ответило «токен недействителен», прослойка передаёт этот ответ как есть. Локальный ответ никогда не подменяет отказ облака.

Про Маркетплейс и про тиражных разработчиков

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

С облачными порталами даже умозрительно ничего не изменить: там сервер авторизации прошит, используется как есть, и в общем всё на этом.

Но есть разработчики тиражных решений, у которых ключевые или, во всяком случае, самые платёжеспособные клиенты сидят на коробке. Если таких разработчиков не устраивает, что работа их приложения у клиента зависит от доступности облачного сервера авторизации, они могут поднять PocketAuth24 у себя и опционально для отдельно взятых порталов работать через него — в режиме прослойки или полностью. Сервер заодно является источником REST-событий. Значит, если не хочется зависеть от скорости очереди событий на стороне Битрикс24, разработчик может стать провайдером событий сам и собственными неимоверными силами гарантировать их своевременную доставку. Или, как минимум, логирование неудачных попыток, что тоже бывает полезно.

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

Бесплатного сыра не бывает: про таблицы, которые наверняка опухнут и будут болеть

Теперь о неприятном, но честном.

PocketAuth24 эмулирует бизнес-логику облака добросовестно, в том числе её аппетит. По стандарту Битрикс24 refresh-токен живёт 180 дней, и в течение этого срока его можно использовать повторно — так видно в записанном облачном трафике. При этом на каждый чих — открытие интерфейса приложения, REST-событие — портал обычно получает новую пару токенов. Кушайте, не обляпайтесь! PocketAuth24 повторяет то же поведение. Значит, таблица токенов растёт, как тесто на батарее.

Я немножечко поработал на эту тему:

  • Каждый час сервер удаляет пары с истёкшим сроком.

  • Включённая по умолчанию чистка (TOKEN_PRUNING=true): когда сервер выдаёт новую пару, он удаляет старые пары того же приложения и пользователя, у которых refresh-токен уже обменяли, а access-токен истёк, и оставляет только пять самых свежих из них (TOKEN_PRUNING_KEEP=5). Пару, чей refresh-токен клиент получил и ни разу не использовал, сервер не трогает: отзывать её до истечения срока нельзя.

  • Если нужно точное поведение облака, чистку можно выключить: TOKEN_PRUNING=false. Тогда каждая пара хранится до конца своих 180 дней.

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

Однако, насколько я помню из разговоров с коллегами, облачный сервер авторизации на самом деле хранит не все токены. Подозреваю, что часть из них — вероятнее всего, refresh-токены, а может быть, и access-токены, точно сказать не могу — вообще не лежит в базе, а представляет собой зашифрованный набор параметров. При проверке сервер расшифровывает токен и сверяет параметры внутри, ничего не ища в таблице. Разве не красиво? В общем, независимо от того, как именно это устроено в облаке, сама идея годная, и я планирую реализовать её в PocketAuth24 в ближайших релизах.

Что ещё не проверено (и где пригодилось бы сообщество)

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

Ещё ограничения, о которых стоит знать заранее:

  • События доставляются один раз и не сохраняются: если обработчик не ответил за 10 секунд или сервер перезапустился, событие потеряно. Постоянная очередь с повторами — в плане, если будут такие запросы. Хотя, как вы знаете, облачный сервер событий повторных отправок не делает.

  • Не поддерживаются grant authorization_code и обработка установки и удаления на стороне сервера.

  • Часть кодов ошибок (invalid_client, неизвестный метод, expired_token) выведена логически, а не записана из облачного трафика.

  • Регистрацию портала защищает обратный прокси: портал не присылает общий секрет, поэтому доступ к /oauth/register/ нужно ограничить по IP-адресам серверов портала. В «правильном» сервере источником подтверждения легитимности регистрации служит хеш лицензионного ключа, который сервер авторизации подтверждает через внутренние службы. С другой стороны, в PocketAuth24 есть белый список.

Поэтому я рассчитываю на сообщество. Если у вас есть тестовый стенд и тяжёлые сценарии — попробуйте. Словили проблему — заведите issue, я постараюсь быстро поправить. Знаете, как поправить, — присылайте pull request. Open source на то и open source.

Фантики: про админку

Админка есть: /admin, многопользовательская, только для чтения, с поиском по порталам, приложениям, метаданным токенов (сами токены и хеши не показываются) и ежедневным счётчикам событий. Сделал её «на сдачу», потому что пока не нашёл для себя практической причины туда ходить: сервер в целом работает сам. Но она есть, и если кому-то понадобятся конкретные сценарии, её легко допилить.

Что ещё в планах

  • полноценный OAuth 2.0 с authorization_code;

  • постоянная очередь событий с повторами доставки и переживанием перезапуска;

  • режим резервирования облака (тот самый «страховочный» сценарий);

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

  • руководство для копий разработки и staging.

А из них вырастают сценарии, которые мне самому любопытны: инспектор событий с повторной отправкой обработчику для отладки, экстренный отзыв всех токенов после утечки, тесты сбоев с коротким сроком жизни токенов и принудительным expired_token, шина событий в брокер сообщений, журнал аудита «кто, когда и для какого приложения получил токен».

В общем, велкам! Репозиторий: github.com/serg-vostrikov-bitrix/pocketauth24. Лицензия MIT. Issue, звёздочки и pull request принимаются в любом порядке и в неограниченных количествах.

И напоследок. Если вам интересно, как такие штуки делаются вместе с AI-агентами (а PocketAuth24, как и этот текст, во многом сделан именно так — вспомните экскаваторы), заходите в мой Telegram-канал AIкселерация. Там про разработку с AI без восторженных придыханий: процессы, инструменты, экономика токенов и грабли, на которые я наступаю первым, чтобы вам не пришлось.

Комментарии (0)