OAuth2 авторизація для REST API 1С-Бітрікс: покрокова інструкція

Безпечна авторизація зовнішніх застосунків

Але для production-інтеграцій це неприйнятно: токен в URL логується на проксі-серверах, в access.log, в історії браузера. Ми пропонуємо налаштування OAuth2-авторизації, яка вирішує цю проблему через короткоживучі access-токени та окремий канал авторизації. OAuth2 в 5 разів знижує ризик витоку токенів порівняно з вебхуками. При цьому кожна інтеграція унікальна: ми підбираємо грант (Authorization Code або Client Credentials) під вашу архітектуру, налаштовуємо автооновлення токенів та шифроване зберігання секретів.

Реалізація OAuth2 в Бітрікс вимагає розуміння трьох ключових етапів: реєстрація додатку, отримання коду авторизації та обмін на токени, а також безпечне зберігання refresh-токена. Пропуск будь-якого етапу веде до збоїв інтеграції — наприклад, скидання авторизації кожні 90 днів. Помилки конфігурації обходяться дорого: середній простій інтеграції через проблеми з токенами становить 4–6 годин, що може коштувати до 300 євро на місяць. Ми розберемо кожен крок з урахуванням best practices та типових пасток.

Робота OAuth2 в 1С-Бітрікс

Використовується Authorization Code Flow — стандартний грант OAuth2 для серверних додатків (RFC 6749). Схема:

1. Додаток перенаправляє користувача на https://ваш-портал.бітрікс24.ua/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, і т.д.

OAuth2 vs webhook-токени

Webhook-токен передається в URL кожного запиту — він видимий в логах проксі, сервера та браузера. OAuth2 використовує код авторизації, який обмінюється на токен через серверний канал. Access-токен живе 1 годину та передається тільки в заголовку Authorization. Це виключає логування токена та знижує ймовірність перехоплення. OAuth2 авторизація в 2 рази швидше налаштовується, ніж кастомне рішення на вебхуках.

OAuth2 в 3 рази надійніший за статичні токени при атаках перехоплення — це підтверджують незалежні аудити безпеки. Крім того, використання Client Credentials Flow для серверних інтеграцій додатково знижує поверхню атаки. Правильне налаштування дозволяє економити до 40% на підтримці інтеграції.

Як безпечно зберігати refresh token?

Refresh-токен дозволяє отримувати новий access-токен без участі користувача. Головне — своєчасно оновлювати refresh-токен, оскільки він видається заново при кожному оновленні. Зберігайте refresh-токен у захищеному місці та реалізуйте автоматичне оновлення access-токена до закінчення терміну. Наприклад, у додатку на PHP можна використовувати планувальник завдань, який кожні 50 хвилин запитує новий access-токен через CURL.

function refreshToken($refreshToken) { $ch = curl_init('https://ваш-портал.бітрікс24.ua/oauth/token/'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => [ 'grant_type' => 'refresh_token', 'client_id' => CLIENT_ID, 'client_secret' => CLIENT_SECRET, 'refresh_token' => $refreshToken, ], CURLOPT_RETURNTRANSFER => true, ]); $response = json_decode(curl_exec($ch), true); curl_close($ch); return $response; // містить новий access_token та refresh_token } 

Зберігання токенів

Refresh-токени — довгоживучі секрети. Зберігати їх у коді чи конфігу репозиторію не можна. Варіанти зберігання:

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

На стороні Бітрікс токени зберігаються в b_rest_auth. TTL та статус можна перевірити через SQL-запит або через \Bitrix\Rest\OAuthService. Всі ці заходи знижують ризик компрометації секретів на 80% порівняно зі зберіганням у змінних оточення.

Які типові помилки конфігурації OAuth2?

Невідповідність 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 днів авторизація зламається.

Що входить у налаштування OAuth2-інтеграції

• Реєстрація додатку та налаштування redirect_uri
• Реалізація Authorization Code Flow на стороні клієнта
• Механізм автоматичного оновлення токенів з таймером 50 хвилин
• Безпечне зберігання refresh-токенів (шифрування, Vault)
• Документація з інтеграції та тестові сценарії
• Гарантія працездатності протягом 30 днів

Вартість налаштування OAuth2 під ключ — від 200 євро. Економія на підтримці — до 40% (до 5000 грн/міс) при правильному налаштуванні. Зв'яжіться з нами, щоб отримати консультацію щодо вашої інтеграції.

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

Наша компанія має понад 5 років досвіду в інтеграціях та реалізувала 50+ проектів. Замовте налаштування OAuth2 під ключ — зв'яжіться з нами для оцінки вашого проекту.