Настройка JWT-токенов для API 1С-Битрикс

Настройка JWT-токенов для API 1С-Битрикс

JWT (JSON Web Token) — стандарт для передачи утверждений между системами в виде подписанного JSON-объекта. В контексте API 1С-Битрикс 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-авторизации в Битрикс

В 1С-Битрикс нет встроенного 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:

// Проверяем логин/пароль пользователя Битрикс
$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 дня в зависимости от сложности ролевой модели.