Перейти к основному содержимому

JWT для мастер-токена

Чтобы получить мастер-токенMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора., интегратор формирует Bearer-токен JWT, подписывает его приватным RSA-ключом и передаёт в метод Создать мастер-токен.

Что получится в конце​

Интеграция получит подписанный JWT, который можно передать в заголовке Authorization: Bearer {integratorToken} при выпуске masterToken.

Что нужно заранее​

Что нужноГде получить
integrator_private.keyРегистрация интегратора
issПодтверждает Служба заботы при регистрации интегратора
subВозвращает Служба заботы после регистрации интегратора
{
  "alg": "RS256",
  "typ": "JWT"
}

Payload​

{
  "iss": "MyCompany",
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "aud": "esa.hr-link.ru",
  "iat": 1680000000,
  "nbf": 1680000000,
  "exp": 1680000600
}
ПолеОписание
issЗначение издателя, подтверждённое при регистрации
subIDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. интегратора из ответа Службы заботы
audВсегда esa.hr-link.ru
iatВремя выпуска токена, Unix timestamp в секундах
nbfНачало действия токена, Unix timestamp в секундах
expВремя истечения токена, Unix timestamp в секундах

Подпись​

Подпишите JWT приватным ключом integrator_private.key. HRlink принимает только RSA-алгоритмы RS256, RS384 и RS512. Рекомендуемый вариант — RS256.

HS256 не поддерживается

Не используйте HS256, HS384 и HS512. При симметричном алгоритме подписи API вернёт ошибку 51.214.

Проверить JWT через jwt.io​

Через jwt.io можно проверить тестовый JWT: алгоритм подписи, payload, формат приватного ключа и итоговый Bearer-токен.

Только для тестовых данных

jwt.io — публичный сайт. Не вставляйте туда боевой приватный ключ, боевой JWT и персональные данные. В рабочей интеграции подписывайте и проверяйте JWT локально или в корпоративном инструменте.

1. Откройте JWT Encoder​

Откройте jwt.io и переключитесь на вкладку JWT Encoder.

2. Выберите алгоритм RS256​

В списке Select signing algorithm выберите RS256. После выбора jwt.io обновит Header до нужного значения:

Вкладка JWT Encoder и выбор алгоритма RS256 на jwt.io 
{
  "alg": "RS256",
  "typ": "JWT"
}

3. Заполните Payload​

В блоке Payload → Data замените пример на значения интегратора:

Поле Payload Data на jwt.io 
{
  "iss": "MyCompany",
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "aud": "esa.hr-link.ru",
  "iat": 1680000000,
  "nbf": 1680000000,
  "exp": 1680000600
}

iat, nbf и exp указывайте как Unix timestamp в секундах. Текущее значение можно получить командой date +%s в Linux/macOS или [int](Get-Date -UFormat %s) в PowerShell.

4. Вставьте приватный ключ​

В блоке Sign JWT: Private Key вставьте тестовый приватный ключ из файла integrator_private.key: весь текст, включая строки -----BEGIN PRIVATE KEY----- и -----END PRIVATE KEY-----. Формат PEM выбран по умолчанию, менять его не нужно.

Поле Sign JWT Private Key и статус Valid private key на jwt.io

Статус Valid private key означает, что jwt.io распознал ключ. Если статус не появился, проверьте, что ключ вставлен целиком и без лишних символов.

5. Скопируйте готовый JWT​

В блоке Encoded JWT jwt.io покажет подписанный токен. Нажмите Copy и передайте значение в заголовке Authorization: Bearer {integratorToken} при вызове метода Создать мастер-токен.

Раздел Encoded JWT и кнопка Copy на jwt.io

Следующий шаг — получить мастер-токен.