Настройка OAuth2-авторизации для API 1С-Битрикс

Настройка OAuth2-авторизации для API 1С-Битрикс

Когда внешнее приложение обращается к REST API 1С-Битрикс, самый простой способ — использовать webhook с токеном в URL. Но для production-интеграций это неприемлемо: токен в URL логируется на прокси-серверах, в access.log, в браузерной истории. OAuth2 решает эту проблему через короткоживущие access-токены и отдельный канал авторизации.

Как работает OAuth2 в 1С-Битрикс

1С-Битрикс реализует Authorization Code Flow — стандартный грант OAuth2 для серверных приложений. Схема:

1. Приложение перенаправляет пользователя на https://your-portal.ru/oauth/authorize/?client_id={id}&response_type=code&redirect_uri={uri}&scope={scopes}
2. Пользователь авторизуется и подтверждает доступ
3. Битрикс перенаправляет на redirect_uri?code={authorization_code}
4. Приложение обменивает код на токены: POST /oauth/token/ с grant_type=authorization_code
5. Битрикс возвращает access_token (TTL: 1 час) и refresh_token (TTL: 90 дней)

Access-токен передаётся в заголовке: Authorization: Bearer {access_token}.

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

Приложение регистрируется в административной части: Marketplace → Приложения → Добавить приложение. Или через API для on-premise: таблица b_rest_app хранит зарегистрированные приложения.

При регистрации указываем:

• client_id и client_secret (генерируются автоматически)
• redirect_uri — должен точно совпадать при запросе кода (включая trailing slash)
• scope — список прав: crm, catalog, sale, user, и т.д.

Обновление токенов

Access-токен живёт 1 час. После истечения нужно запросить новый через refresh-токен:

POST /oauth/token/
grant_type=refresh_token
&client_id={id}
&client_secret={secret}
&refresh_token={refresh_token}

Если refresh-токен тоже истёк (90 дней без использования) — нужна повторная авторизация пользователя. Для сервисных интеграций без пользовательского контекста используем Client Credentials Flow через вебхуки с фиксированными токенами, либо настраиваем сервисного пользователя и автоматически обновляем refresh-токен.

Хранение токенов

Refresh-токены — долгоживущие секреты. Хранить их в коде или конфиге репозитория нельзя. Варианты хранения:

• В зашифрованном виде в БД приложения (AES-256)
• В сервисе управления секретами (HashiCorp Vault, AWS Secrets Manager)
• Для простых интеграций — в файле вне веб-корня с правами 600

На стороне Битрикс токены хранятся в b_rest_auth. TTL и статус можно проверить через SQL-запрос или через \Bitrix\Rest\OAuthService.

Типичные ошибки конфигурации

Несовпадение redirect_uri. OAuth2 чувствителен к точному совпадению URI. https://app.example.com/callback и https://app.example.com/callback/ — разные URI. Битрикс вернёт error: redirect_uri_mismatch.

Слишком широкий scope. Запрашивать * (все права) — плохая практика безопасности. Запрашиваем минимально необходимый набор прав. Если интеграция только читает каталог — только catalog.

Refresh-токен не обновляется. При получении нового access-токена через refresh, Битрикс также выдаёт новый refresh-токен. Если приложение сохраняет только старый refresh-токен — через 90 дней авторизация сломается.

Ориентиры по срокам

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