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

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

openssl genrsa -des3 -out integrator_private.key 2048

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

Файл private_key.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

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

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

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

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

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

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

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

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.crt и 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.3. данной инструкции>"
}'

3.2.2. Ответ

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

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

Запрос

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"


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