JWT (JSON Web Token) в Битрикс

JWT (JSON Web Token) — стандарт для передачи данных между клиентом и сервером в формате JSON. Токен состоит из трех частей:

1. header заголовок который указывает алгоритм подписи
2. payload данные в которых передают информацию
3. signature подпись, защищает токен от подделки

Варианты использования

1. Авторизация без сессий. Пользователь остается авторизованным, пока токен действителен
2. Защищенные запросы к API. Сервер проверяет подпись токена
3. Обмен данными между сервисами. Например, обмен между сайтом и мобильным приложением

Создаем токен

Чтобы создать JWT-токен, используйте класс Bitrix\Main\Web\JWT:

use Bitrix\Main\Web\JWT;
// храните его в безопасности
$secret = 'ваш-секретный-ключ';
$payload = [
    // ID пользователя
    'user_id' => 123,
    // дополнительные данные
    'name' => 'Иван',
];
// метод encode создает токен с алгоритмом HS256 по умолчанию
$jwt = JWT::encode($payload, $secret);

// или с другим алгоритмом, например RS256
// $jwt = JWT::encode($payload, $privateKey, 'RS256');

• Ключ $secret должен быть длинным и содержать случайные символы
• В payload можно передавать любые данные
• По умолчанию используется алгоритм HS256

Ограничение времени действия токена

Чтобы ограничить время действия токена, добавьте в payload параметры:

• iat время создания
• exp срок действия
• nbf время начала работы

use Bitrix\Main\Web\JWT;

$secret = 'секретный-ключ';
$payload = [
    'user_id' => 123,
    'name' => 'Иван',
    // токен создастся сейчас
    'iat' => time(),
    // истечет через 1 час
    'exp' => time() + 3600,
    // станет активен через 5 минут
    'nbf' => time() + 300,
];

$jwt = JWT::encode($payload, $secret);

Учет рассинхронизации времени

В распределенных системах часы серверов и клиентов могут расходиться. Параметр leeway задает допустимое отклонение в секундах:

// разрешено отклонение на 30 секунд
JWT::$leeway = 30;
// токен истечет через 1 час
$payload = ['user_id' => 42, 'exp' => time() + 3600];
$token = JWT::encode($payload, 'secret');
// учитывает параметр leeway
$decoded = JWT::decode($token, 'secret', ['HS256']);

Проверка токена

Чтобы проверить токен и получить данные используйте метод decode:

use Bitrix\Main\Web\JWT;

$secret = 'ваш-секретный-ключ';
$jwt = 'токен-полученный-от-клиента';

try {
    $payload = JWT::decode($jwt, $secret, ['HS256']);
    // токен верный, работаем с данными:
    echo 'Пользователь: ' . $payload->name;
} catch (Exception $e) {
    // токен не прошёл проверку
    echo 'Ошибка: ' . $e->getMessage();
}

Всегда указывайте алгоритм в параметрах метода, например, ['HS256']. Иначе система может принять токен, подписанный слабым алгоритмом.

Возможные ошибки

• Неверная подпись — ключ не совпадает
• Токен просрочен — если указан параметр exp
• Токен еще не активен — если указан параметр nbf

Поддерживаемые алгоритмы подписи

Класс Bitrix\Main\Web\JWT поддерживает алгоритмы:

Алгоритмы HS проще в использовании, так как они используют один секретный ключ.

лгоритмы RS и ES — безопаснее, но требуют два ключа: публичный и приватный.

Рекомендации по безопасности

1. Не храните важные данные в JWT — токен можно раскодировать. Важные данные лучше хранить на сервере, а в токене передавать только ссылки или идентификаторы
2. Храните ключ надежно — токены можно подделать при наличии ключа
3. Используйте HTTPS — зашифрованное соединение защитит от перехвата токена
4. Выбирайте надежный алгоритм — HS256 для простых случаев или RS256 для повышенной безопасности