Налаштування JWT-токенів для API 1С-Бітрікс

Налаштування JWT-токенів для API 1С-Bitrix

JWT (JSON Web Token) — стандарт для передачі твердження між системами у вигляді підписаного JSON-об'єкту. У контексті API 1С-Bitrix JWT використовується для авторизації запитів: клієнт пред'являє токен, сервер перевіряє підпис та дозволяє або відхиляє запит.

Що таке JWT: структура

Токен складається з трьох частин, розділених крапкою: header.payload.signature.

• Header — алгоритм підпису: {"alg": "HS256", "typ": "JWT"}.
• Payload — дані: {"sub": "user_id", "iat": 1700000000, "exp": 1700003600, "role": "api_client"}.
• Signature — HMAC-SHA256 від header+payload з секретним ключем.

Токен не шифрується — payload читаємий. Але підробити підпис без секретного ключа неможливо.

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

В 1С-Bitrix немає вбудованого JWT-провайдера для REST API. JWT-аутентифікація реалізується через кастомний обробник у складі власного API-модуля або через хук в /local/php_interface/init.php.

Структура обробника:

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;
        }
    }
}

Бібліотека firebase/php-jwt встановлюється через Composer в /local/:

composer require firebase/php-jwt

Видача токенів: ендпоінт аутентифікації

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

// Перевіряємо логін/пароль користувача Bitrix
$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 з прив'язкою до користувача та можливістю відпалу.

Секретний ключ

Секрет для підпису зберігається в b_option:

// Генерація при встановленні модуля
$secret = bin2hex(random_bytes(32)); // 64 символи
\Bitrix\Main\Config\Option::set('my_api', 'jwt_secret', $secret);

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

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

// На початку кожного 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 збільшує розмір токена. Права, які часто змінюються, краще перевіряти в БД при кожному запиті.

Налаштування JWT-авторизації для нового API — 1-2 дні залежно від складності ролевої моделі.