Рукопожатие установки OAuth

Что делает

Это недостающее звено между «у меня есть clientId/clientSecret» и «у меня есть рабочий клиент B24OAuth». Приложение Bitrix24, установленное по OAuth, получает события ONAPPINSTALL, ONAPPUPDATE и ONAPPUNINSTALL на ваш настроенный URL обработчика. Этот рецепт:

1. Принимает событие установки и сохраняет OAuth-токены по порталам (member_id как ключ).
2. Предоставляет clientForMember(memberId) — создаёт экземпляр B24OAuth из сохранённых токенов, прикрепляет callback обновления, чтобы следующая обновлённая пара автоматически записывалась обратно в хранилище.
3. Удаляет учётные данные при удалении.
4. Демонстрирует REST-вызов по порталу (profile) через полученный клиент.

Используйте это как каркас для мультитенантного бэкенда, который обслуживает много порталов Bitrix24 из одного OAuth-приложения.

Стек

Node.js 18+, express.

Установка

pnpm add express

Переменные окружения

export PORT=3001                             # по умолчанию
export B24_CLIENT_ID='local.abc123'          # из вашей dev-консоли Bitrix24
export B24_CLIENT_SECRET='...'

В dev-консоли Bitrix24:

• URL обработчика установки: https://your-server.example.com/install
• URL обработчика удаления: https://your-server.example.com/uninstall

Для локальной разработки пробросьте через npx ngrok http 3001.

Запуск

npx tsx 12-oauth-install.ts

Затем запустите рукопожатие, установив приложение на портал Bitrix24. Проверьте через:

curl https://your-server.example.com/portal/<memberId>/profile

Исходник

skills/b24jssdk-recipes/examples/12-oauth-install.ts.

Примечания

• Хранилище — JSON-файл для демо (.oauth-store.json). Для production замените на Postgres / Redis / ваше реальное хранилище.
• application_token — Bitrix24 присылает его и с событиями установки, и удаления. Рецепт его сохраняет, но не проверяет при удалении — в production сравнивайте значение перед удалением учётных данных, чтобы защититься от подделанных вызовов удаления.
• setCallbackRefreshAuth подключается при каждом вызове clientForMember(). Это гарантирует, что в хранилище всегда последняя пара токенов после авто-обновления SDK при 401.
• Всегда возвращайте 200 на endpoint-ы установки / удаления. Не-2xx запускает повторы Bitrix24 на 24 часа.
• Для нескольких воркеров, обслуживающих один портал, используйте транзакционное хранилище (Postgres ON CONFLICT UPDATE), чтобы параллельные обновления не теряли токены.
• Для более широкого мультитенантного паттерна по порталам (стратегия кэша, жизненный цикл, отозванные установки) этот рецепт — основа: оберните clientForMember в LRU-кэш по ключу memberId для «горячих» порталов.