Налаштування 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. 1С-Бітрікс перенаправляє на redirect_uri?code={authorization_code}
4. Застосунок обмінює код на токени: POST /oauth/token/ з grant_type=authorization_code
5. 1С-Бітрікс повертає 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

На стороні 1С-Бітрікс токени зберігаються в b_rest_auth. TTL та статус можна перевірити через SQL-запит або через \Bitrix\Rest\OAuthService.

Типові помилки конфігурації

Невідповідність redirect_uri. OAuth2 чутливий до точного збігу URI. https://app.example.com/callback та https://app.example.com/callback/ — різні URI. 1С-Бітрікс поверне error: redirect_uri_mismatch.

Надто широкий scope. Запитувати * (всі права) — погана практика безпеки. Запитуємо мінімально необхідний набір прав. Якщо інтеграція лише читає каталог — тільки catalog.

Refresh-токен не оновлюється. При отриманні нового access-токену через refresh, 1С-Бітрікс також видає новий refresh-токен. Якщо застосунок зберігає лише старий refresh-токен — через 90 днів авторизація зламається.

Орієнтири за термінами

Вартість розраховується індивідуально після аналізу вимог та архітектури інтегрованих систем.