OAuth-подключения

Интеграции типа OAUTH2 используют стандартный Authorization Code Flow. Пользователь проходит авторизацию на стороне внешнего сервиса — платформа не получает и не хранит логин и пароль.

Как работает OAuth-поток

1. Пользователь нажимает «Подключить» в интерфейсе
2. Платформа формирует URL авторизации с подписанным state
3. Браузер перенаправляет на страницу внешнего сервиса
4. Пользователь подтверждает разрешения
5. Внешний сервис перенаправляет обратно с кодом авторизации
6. Платформа обменивает код на токены и сохраняет их зашифрованными
7. Установка переходит в статус ACTIVE

Начало авторизации

GET /api/v1/integrations/oauth/:slug/authorize

Требует аутентификации. Возвращает 302 Redirect на страницу авторизации внешнего сервиса.

State-параметр подписывается HMAC-SHA256 и содержит идентификатор тенанта, пользователя и временную метку (TTL 10 минут). Это защищает от CSRF-атак.

Обработка callback

GET /api/v1/integrations/oauth/:slug/callback

Публичный эндпоинт — не требует аутентификации (запрос приходит от внешнего сервиса).

Платформа:

1. Проверяет подпись state
2. Проверяет TTL (не старше 10 минут)
3. Обменивает code на access_token / refresh_token
4. Сохраняет токены в зашифрованном виде
5. Обновляет статус установки на ACTIVE
6. Перенаправляет пользователя обратно в интерфейс

При ошибке авторизации браузер перенаправляется на страницу ошибки с параметром ?error=....

Отзыв токена

POST /api/v1/integrations/oauth/:slug/revoke

{ "installationId": "550e8400-..." }

Отзывает токен на стороне внешнего сервиса (если сервис поддерживает revoke endpoint) и удаляет сохранённые токены. Установка переходит в статус PENDING_CONFIG.

Безопасность хранения токенов

OAuth-токены хранятся в поле oauthTokenData модели IntegrationInstallation в зашифрованном виде (AES-256-GCM с ротируемым ключом). Токены никогда не возвращаются клиенту в API-ответах.

Поддерживаемые OAuth-сервисы

Интеграция	Сервис
Google Sheets Export	Google OAuth 2.0
Битрикс24	Битрикс24 OAuth

Список расширяется. Конкретные authorizeUrl и tokenUrl задаются в capabilitiesSchema определения интеграции.