Оглавление

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.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.crt

Файл integrator.crt необходимо будет далее передать в службу поддержки HRlink

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    {
      "alg": "RS256",
      "typ": "JWT"
    }


    alg - алгоритм шифрования RS256
    typ - тип токена JWT
  3. Поле 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/

  4. В поля VERIFY SIGNATURE заполнить содержимое из файлов integrator_private.key и integrator_pubkey.pem.
  5. В поле 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)





  • No labels