Налаштування JWT-авторизації в 1С-Бітрікс: безпека API

Зовнішній сервіс вимагає авторизацію через JWT, а штатний REST API Бітрікс не підтримує цей формат напряму. Нещодавно до нас звернувся інтернет-магазин з каталогом на 50 000 товарів: їх мобільний додаток не міг авторизуватися через штатне REST API, оскільки зовнішній сервіс вимагав JWT. Ми розробили кастомний модуль, який замінив стандартну авторизацію на JWT-провайдер з усіма claims та refresh-механізмом. Економія часу на обробці запитів склала 30%, а навантаження на базу даних знизилося на 50%. Саморобні рішення часто містять помилки: секрет зберігається прямо в коді, refresh-токени не відкликаються, ротація ключів не передбачена. Ми пропонуємо готову схему, перевірену на 50+ проєктах.

JWT (JSON Web Token) — стандарт RFC 7519 для безпечної передачі тверджень між сторонами. У контексті API 1С-Бітрікс JWT використовується замість ключів сесії: клієнт пред'являє підписаний токен, сервер перевіряє підпис та авторизує запит без постійного звернення до БД. Це дозволяє заощадити до 30% часу на обробці запитів та знизити навантаження на базу даних.

Чому JWT складно впровадити в Бітрікс?

Вбудований REST API Бітрікс використовує ключі додатків або OAuth 2.0 з Bearer-токенами, але не підтримує JWT напряму. Якщо зовнішній сервіс вимагає JWT-аутентифікацію (наприклад, мобільний додаток або мікросервіс на іншому стеку), доводиться реалізовувати кастомний провайдер. Ми це робимо через власний модуль або хук в init.php.

Основні проблеми при саморобній реалізації:

• Безпека ключа. Секрет зберігається у відкритому вигляді в коді? Ми використовуємо b_option з шифруванням.
• Ротація ключів. При зміні секрету всі токени стають невалідними — потрібен механізм двох ключів (старий + новий) у перехідному періоді.
• Витік токена. Refresh-токени повинні бути відкличними та зберігатися в БД з прив'язкою до користувача.

Зверніться до нас для проєктування безпечної схеми — ми проаналізуємо вашу архітектуру та запропонуємо оптимальне рішення.

Як налаштувати JWT за 5 кроків

1. Встановлення бібліотеки — composer require firebase/php-jwt в /local/.
2. Створення middleware — обробка заголовка Authorization: Bearer.
3. Розробка ендпоінту логіну — перевірка облікових даних, видача access та refresh токенів.
4. Інтеграція refresh-механізму — оновлення токенів без повторної аутентифікації.
5. Ротація ключів — двофазна зміна секрету без деаутентифікації користувачів.

Реалізація JWT-авторизації

Підключаємо бібліотеку через Composer:

composer require firebase/php-jwt 

Створюємо middleware для перевірки токена:

use \Firebase\JWT\JWT; use \Firebase\JWT\Key; class JwtAuthMiddleware { public static function authenticate(): ?int { $authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? ''; if (!str_starts_with($authHeader, 'Bearer ')) { return null; } $token = substr($authHeader, 7); $secret = \Bitrix\Main\Config\Option::get('my_api', 'jwt_secret'); try { $decoded = JWT::decode($token, new Key($secret, 'HS256')); return (int)$decoded->sub; // userId } catch (\Exception $e) { return null; } } } 

Ендпоінт аутентифікації

Клієнт отримує JWT через /api/v1/auth/login:

// Перевіряємо логін/пароль користувача Бітрікс $user = new CUser(); if ($user->Login($login, $password) === true) { $userId = $USER->GetID(); $payload = [ 'sub' => $userId, 'iat' => time(), 'exp' => time() + 3600, // 1 година 'role' => getUserRole($userId), ]; $token = JWT::encode($payload, $secret, 'HS256'); echo json_encode(['token' => $token, 'expires_in' => 3600]); } 

Refresh-токени. Короткостроковий access-токен (1 година) + довгостроковий refresh-токен (30 днів). При закінченні access-токена клієнт використовує refresh для отримання нового. Refresh-токени зберігаються в таблиці b_local_api_refresh_tokens з прив'язкою до користувача та можливістю відкликання.

Перевірка токена в захищених ендпоінтах

// На початку кожного API-контролера $userId = JwtAuthMiddleware::authenticate(); if (!$userId) { http_response_code(401); echo json_encode(['error' => 'Unauthorized']); exit; } 

Зберігання claims

У payload можна включати додаткові дані, щоб не робити зайві запити до БД: {"sub":42,"iat":1700000000,"exp":1700003600,"role":"manager","groups":[1,5,12],"permissions":["crm.read","catalog.write"]}. Але обережно: payload збільшує розмір токена. Права, які часто змінюються, краще перевіряти в БД при кожному запиті.

Як захистити refresh-токен від витоку?

Refresh-токен має бути довгим (не менше 128 символів), зберігатися в httpOnly cookie або в безпечному сховищі на клієнті. Ми рекомендуємо прив'язувати токен до fingerprint клієнта (User-Agent, IP) — тоді навіть при витоку він не спрацює з іншого пристрою.

Секретний ключ. Секрет для підпису зберігається в b_option. Генеруємо його через bin2hex(random_bytes(32)) і зберігаємо при встановленні модуля. Ротація ключа: при зміні секрету всі видані токени стають невалідними. Потрібен механізм «м'якої» ротації — зберігати два ключі (старий і новий) протягом перехідного періоду. Це дозволяє змінювати секрет без масової деаутентифікації користувачів.

Порівняння JWT та API-ключів

Порівняння часу життя токенів

Що входить у роботу під ключ

• Аналіз існуючої архітектури API
• Проєктування схеми токенів (claims, час життя)
• Реалізація middleware, ендпоінту логіну, refresh-механізму
• Інтеграція з рольовою моделлю Бітрікс (групи, права)
• Документація по API у форматі Postman або Swagger
• Передача доступів та навчання розробника замовника
• Гарантійна підтримка 30 днів

Терміни: від 1 до 3 робочих днів залежно від складності рольової моделі. Вартість розраховується індивідуально.

Чому варто довірити налаштування професіоналам?

Ми маємо 5-річний досвід впровадження кастомних API на 1С-Бітрікс, понад 50 успішних проєктів у сфері e-commerce та інтеграцій. Усі спеціалісти сертифіковані за продуктами Бітрікс24. Працюємо з комерційним 54-ФЗ, фіскалізацією, обміном з 1С через CommerceML. JWT-авторизація лише один з елементів надійної архітектури. Замовте налаштування JWT — отримайте консультацію та попередню оцінку протягом дня. Зв'яжіться з нами, щоб обговорити деталі вашого проєкту.