1. Создать сертификат интегратора

1.1. Создать приватный ключ для выпуска сертификата

openssl genrsa -des3 -out integrator_private.key 2048

Скрипт запросит ввести и подтвердить "PEM pass phrase" - это пароль к сертификату. Он должен состоять минимум из 4 символов, необходимо его сохранить и хранить в секрете. В результате будет создан файл с ключом сертификата integrator_private.key.

Файл integrator_private.key и его содержимое никому не передавать и хранить в секрете!

1.2. Сгенерировать сертификат

openssl req -newkey rsa:2048 -nodes -keyout integrator_private.key -x509 -days 365 -out integrator_private.crt

Скрипт запросит данные для сертификата. Заполнение данных опционально, они не участвуют в проверке подлинности.

Country Name (2 letter code) [AU]: RU
State or Province Name (full name) [Some-State]: Москва
Locality Name (eg, city) []: город
Organization Name (eg, company) [Internet Widgits Pty Ltd]: Company
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []: Company
Email Address []: some@email.com

С помощью этой команды мы выпускаем сертификат, подписанный приватным ключом. В примере сертификат выпускается на 365 дней. Этот срок можно изменить на усмотрение интегратора.

В результате будет создан файл с сертификатом интегратора integrator_private.crt

Файл integrator_private.crt и его содержимое никому не передавать и хранить в секрете!

1.3. Создать публичный ключ сертификата

openssl x509 -pubkey -noout -in integrator_private.crt > integrator_pubkey.pem

С помощью этой команды мы генерируем публичный ключ для сертификата. Этим ключом HRlink будет проверять достоверность подписи токена интегратора. В результате будет создан файл с публичным ключом integrator_pubkey.pem

Файл integrator_pubkey.pem не является секретом.

2. Зарегистрировать интегратора в HRlink

2.1. Обратиться в Службу заботы HRlink

Любым удобным вам способом. Например, в телеграм-бота или на почту help@hr-link.ru

В запросе необходимо указать следующие данные:

Тенант, для которого необходимо зарегистрировать интегратора
Имя интегратора в английской транслитерации. Например, Company.
Значение поля издателя (issuer) Bearer-токена. Может совпадать с именем интегратора. Это поле будет использоваться интегратором для генерации Bearer-токена.
Сертификат Интегратора - сертификат публичного ключа Интегратора стандарта X.509 в текстовом формате PEM. Это файл integrator_pubkey.pem, который был сгенерирован выше по тексту.
Контактный email.

2.2. Получить ответ от Службы заботы

В ответе будет предоставлен ID интегратора в системе HRlink, он потребуется для формирования Bearer-токена.

3. Получить Мастер-токен

3.1. Сформировать Bearer-токен, который будем менять на мастер-токен

Bearer-токен - это JWT-токен, подписанный приватным ключом интегратора - файлом integrator_private.key, который мы выпустили в п. 1.1. выше по тексту.

Bearer-токен должен генерироваться программными средствами (автоматически), но далее, для наглядности, мы рассмотрим ручной выпуск.

Для создания JWT-токена и его подписания воспользуемся сайтом https://jwt.io/
Если использовались скрпты из данной инструкции, то поле HEADER:ALGORITHM & TOKEN TYPE должно содержать следующие поля:
{
"alg": "RS256",
"typ": "JWT"
}

alg - алгоритм шифрования RS256
typ - тип токена JWT
Поле PAYLOAD:DATA должно содержать следующие поля:
{
"iss": "Company",
"sub": "9eacedbf-48e3-4bf3-a00c-78b58b2721d7",
"aud": "esa.hr-link.ru",
"iat": 1735111111,
"nbf": 1735111111,
"exp": 1735679400
}

iss - Значение поля издателя (issuer) Bearer-токена, которое мы зарегистрировали через Службу заботы в п. 2.1.3. данной инструкции.
sub - ID интегратора, который мы получили в ответе от Службы заботы в п. 2.2. данной инструкции.
aud - всегда равно esa.hr-link.ru
iat - момент выпуска токена в формате unixtimestamp.
nbf - момент начала действия токена в формате unixtimestamp.
exp - момент истечения срока действия токена в формате unixtimestamp. Не может быть больше 10 минут от момента начала действия (есть возможность изменить ограничение через Службу заботы)
Для удобной генерацииunixtimestamp можно воспользоваться сайтом https://www.unixtimestamp.com/
В поля VERIFY SIGNATURE заполнить содержимое из файлов integrator_private.key и integrator_pubkey.pem.
В поле Encoded сгенерируется подписанный Bearer-токен, который мы будем обменивать на мастер-токен.

3.2. Обменять Bearer-токен на мастер-токен

https://docs.myhrlink.ru/public/openapi/hr-link/#tag/authCurrentUser/operation/createMasterTokens

3.2.1. Запрос

curl -X POST --location "https://esa.hr-link.ru/api/v1/masterTokens" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer <Сгенерированный в п.3.1.5 JWT-токен>" \
-d '{
"tenantHost": "<Тенант, указанный п. 2.1.1. данной инструкции>"
}'

3.2.2. Ответ

{
"result": true,
"masterToken": "eyJ4NXUiOiJodHRw<пропущено>FhOSJ9.p4-yFMrMVT9WzU<пропущено>l9HauDPlWhWwnEROA.uBwKP<пропущено>LcTim34jw4o"
}

4. Выполнить запрос с использованием мастер-токена

curl -X GET --location "https://<tenantHost>/api/v1/currentUser" --http1.1 \
-H "Accept: application/json" \
-H "Master-Api-Token: eyJ4NXUiOiJodHRw<пропущено>FhOSJ9.p4-yFMrMVT9WzU<пропущено>l9HauDPlWhWwnEROA.uBwKP<пропущено>LcTim34jw4o" \
-H "Impersonated-User-Id: 1519393e-4a3c-4e2e-8468-025f9e718051" \
-H "Impersonated-User-Id-Type: HR_LINK_ID"

Master-Api-Token - токен, который был получен в п. 3.2.2. данной инструкции
Impersonated-User-Id - ID пользователя, от имени которого должен быть выполнен запрос.
Impersonated-User-Id-Type - тип ID пользователя
- HR_LINK_ID - значение в Impersonated-User-Id воспринимается как ID пользователя внутри HRlink.
- SNILS - значение в Impersonated-User-Id воспринимается как СНИЛС физлица пользователя.
- EXTERNAL_ID - значение в Impersonated-User-Id воспринимается как значение ID пользователя во внешней системе. Поиск пользователя по ID из внешней системы может происходить по-разному, в зависимости от наличия и значения заголовка Impersonated-User-Id-External-System-Type.
  - Если Impersonated-User-Id-External-System-Type не задан или пустой, то выполняется поиск по ID пользователя клиента во внешней системе, указанному при создании физлица в поле externalId (см. Метод создания физлица).
  - Если Impersonated-User-Id-External-System-Type задан, то выполняется поиск по ID пользователя во внешней системе с заданным типом, указанных при создании физлица в массиве userExternalIds в одном из объектов в полях systemType и value соответственно (см. Метод создания физлица).
- Если тип не задан, то значение по умолчанию считается HR_LINK_ID.

Если Impersonated-User-Id-Type = HR_LINK_ID, то Impersonated-User-Id- это идентификатор, который возвращается в поле id метода currentUser (не путать с clientUserId)

Оглавление