В данном разделе описывается порядок действий, необходимых для реализации сложных кейсов инетграции:

  • интеграция с  ИС Клиента для Сотрудников
  • использование сквозной авторзиации
  • встраивание функционала HRlink через webview


Словарь терминов

  • Единый Сервис Авторизации (ЕСА) - Сервис HRlink, используемый для авторизации внешних систем и пользователей, связанных с ними.

  • Bearer-токен - Токен типа JWT для аутентификации запросов Интегратора к ЕСА по схеме Bearer.

  • Интегратор - Тенант системы HRlink, которому нужна интеграция с системой HRlink.

  • Мастер-токен - Токен для аутентификации запросов Интегратора к HRlink для выполнения операций от имени определенного пользователя HRlink, принадлежащего тенанту Интегратора.

Регистрация Интегратора в HRlink

Регистрация производится по запросу Интегратора в службу заботы о клиентах HRlink.

Необходимые данные для регистрации:

  1. Имя Интегратора. Например, Company.

  2. Значение поля издателя (issuer) Bearer-токена. Может совпадать с именем Интегратора. Это поле используется интегратором для генерации Bearer-токена и используется при аутентификации для получения мастер-токена (см. ниже).

  3. Сертификат Интегратора - сертификат публичного ключа Интегратора стандарта X.509 в текстовом формате PEM. Ожидается использование сертификата конечного пользователя (LEAF), а не промежуточного сертификата (INTERMEDIATE).

  4. Контактный email.

В результате регистрации:

  1. В ЕСА вносятся записи об Интеграторе и его сертификате.

  2. Интегратору предоставляются данные для генерации Bearer-токена.

После регистрации Интегратор создаёт свой Bearer-токен и может использовать его в запросе к ЕСА для получения мастер-токена.

Получение сертификата открытого ключа ЕСА

Метод

GET https://esa.hr-link.ru/certificate возвращает сертификат ЕСА в формате PEM.

``` 
-----BEGIN CERTIFICATE----- 
MIIFmDCCA4CgAwIBAgICEAIwDQYJKoZIhvcNAQELBQAwgYExCzAJBgNVBAYTAkdC 
... 
... 
... 
i3mabA2lEfMRvBS6P0DIJAtehulZMbchk0UJoLm4jNWip0aGC8mTtxJ9n/Y= 
-----END CERTIFICATE----- 
```

Тип содержимого ответа - text/html.



Мастер-токен

Создание мастер-токена

Используется для получения мастер-токена Интегратором.

Метод

POST https://esa.hr-link.ru/api/v1/masterTokens

Content-Type: application/json

``` 
{
    "tenantHost": "<host>" 
} 
```

Где <host> - хост тенанта Интегратора в HRlink, для которого нужно выпустить мастер-токен. Обязательное поле.

Заголовки

Authorization: Bearer <token>

Где <token> - это Bearer-токен типа JWT, созданный Интегратором на основании данных, полученных при регистрации.

Подробнее см. Получение мастер-токена

Валидации

  • В HTTP-запросе есть заголовок для аутентификации запроса.

  • В заголовке для аутентификации запроса содержится Bearer-токен типа JWT.

  • JWT-токен содержит все обязательные данные (см. Получение мастер-токена).

  • Существует интегратор с ID, равным Subject токена.

  • У интегратора существует сертификат открытого ключа.

  • JWT-токен подписан алгоритмом RSA с использованием закрытого ключа, соответствующего сертификату открытого ключа интегратора.

  • Токен можно использовать в данный момент времени.

  • Поля токена сформированы корректно согласно требованиям (см. Получение мастер-токена).

Ответ

``` 
{
    "result": true, 
    "masterToken": "<token>" 
}
```

Где <token> - это мастер-токен типа JWT, созданный ЕСА для тенанта Интегратора.

Получение мастер-токена

Для получения мастер-токена Интегратор вызывает API метод создания мастер-токена на ЕСА и в заголовке Authorization после ключевого слова Bearer передаёт свой Bearer-токен.

  • Тип токена: JWT.

  • Алгоритм подписи токена: RS256 или RS384 или RS512. Токен подписан ключом, соответствующим сертификату Интегратора, который был предоставлен Интегратором при регистрации.

Поля тела (payload) токена:

  • iss - Issuer - Издатель Bearer-токена. Значение должно быть предоставлено Интегратором при регистрации.

    • Тип: string.

    • Формат: строка.

  • sub - Subject - ID Интегратора в ЕСА, который был получен Интегратором после регистрации.

    • Тип: string.

    • Формат: UUID.

  • aud - Audience - Хост ЕСА, равный esa.hr-link.ru.

    • Тип: string.

    • Формат: строка.

  • exp - Expiration Time - Момент времени, когда истекает время действия токена.

    • Тип: number.

    • Формат: Unix Time, количество секунд.

  • nbf - Not Before - Момент времени, когда начинается время действия токена.

    • Тип: number.

    • Формат: Unix Time, количество секунд.

  • iat - Issued at - Момент времени, когда токен был выдан.

    • Тип: number.

    • Формат: Unix Time, количество секунд.

Все поля токена обязательны для заполнения.

Время жизни Bearer-токена (exp - nbf) не должно превышать 10 минут. Если требуется изменить это ограничение, обратитесь в службу заботы о клиентах HRlink.

```
eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJDb21wYW55Iiwic3ViIjoiNTU3ZTVhZjQtNGU1My00NzNkLTlhOWQtNzZiNjlmMzgyM2MyIiwiYXVkIjoiZXNhLmhyLWxpbmsucnUiLCJpYXQiOjE2NTAwMDAwMDAsImV4cCI6MTY1MDAwMDYwMCwibmJmIjoxNjUwMDAwMDAwfQ.e8qAICTHwMgxcVZ-w85FfgxEa7Ke48l-rpON09ofQ-e1u-w17BUTHnCoB7MOyghA4VedhYpOZf3ZXqL87qAzyFxSaDYzcCgwrpWkQybtlMBUT-QHS5rRkUoFWquCjE2q9nmrY4cEE_jqcEoTb2G6wKWeXd-ArA1gzjkiqRxlowd9xB57hG13cndQIDw1_0oSRSRUXhev0L0Y6MwzWEDXPGXH-7sP4WMNfIRsUn1fO5Mo5bfH5Iyq6Rg7oL0w8jWc6iFFGxK_5njQOSGG90lMs6M4uyMfq0WJ49Vc8djlTRRFPoK3HP7z7qWrV46zA-j19PLH5pRu4NUdCB6557v7ew

```
``` 
{
    "alg": "RS256" 
}
```
``` 
{
    "iss": "Company", 
    "sub": "557e5af4-4e53-473d-9a9d-76b69f3823c2", 
    "aud": "esa.hr-link.ru", 
    "exp": 1650000600, 
    "nbf": 1650000000, 
    "iat": 1650000000 
} 
```

Будет получен ответ с полем masterToken, содержащим мастер-токен, созданный для Интегратора.

  • Тип токена: JWT.

  • Алгоритм подписи токена: RS256. Токен подписан закрытым ключом, соответствующим сертификату открытого ключа ЕСА

Поля заголовка (header) токена:

  • alg - Algorithm - Алгоритм, которым подписан токен, равен RS256.

  • x5u - x.509 Certificate Chain URL - URL для получения сертификата ЕСА для проверки подписи токена. Единственным доверенным значением является https://esa.hr-link.ru/certificate.

Поля тела (payload) токена:

  • iss - Issuer - Хост ЕСА, равный esa.hr-link.ru.

  • sub - Subject - ID Интегратора в ЕСА.

  • aud - Audience - Хост тенанта Интегратора в HRlink, который был указан в теле запроса.

  • exp - Expiration Time - Момент времени, когда истекает время действия токена.

  • nbf - Not Before - Момент времени, когда начинается время действия токена.

  • iat - Issued at - Момент времени, когда токен был выдан.

  • jti - JWT ID - ID выданного токена на ЕСА.

Время жизни мастер-токена (exp - nbf) ограничено 60 минутами. Если требуется изменить это ограничение, обратитесь в службу заботы о клиентах HRlink.

```
eyJ4NXUiOiJodHRwczovL2VzYS5oci1saW5rLnJ1L2NlcnRpZmljYXRlIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI1NTdlNWFmNC00ZTUzLTQ3M2QtOWE5ZC03NmI2OWYzODIzYzIiLCJhdWQiOiJjb21wYW55LmhyLWxpbmsucnUiLCJuYmYiOjE2NTAwMDAwMDAsImlzcyI6ImVzYS5oci1saW5rLnJ1IiwiZXhwIjoxNjUwMDAzNjAwLCJpYXQiOjE2NTAwMDAwMDAsImp0aSI6ImQwZmU3YWFlLTliOWMtNDk2NC1hYjE3LWFmODUyZWIzMDk1YiJ9.flTLPs3XCQ1Q3l-PGUQnmIL7iJFe7QkfHSNMd_zun1p0J3mWbSUKS2yrbkhfcH4FbXcRkUoiEiiVPmdsGRiDDRfZEpSerdqmsW1OqCgKFi6_2NqfcCVeXXGuLem3HCAgpiI4q8gXFzJG-Hj-lE77D_VYeWWCaWo0AmXvOkk6cal7WILXhIoW_Je1lYkRnWiBFOTCIn_wBz870a6m89rsK8HUw1cAh_7fIKKe2O92wNoXYYuCQifbO7VFwvqIcMJf_qD87u8l7t3sKnyQXMNwAy86B8JHbo3r7HtncUGk7AxbTjtszECVqgIO_7zZa-DZ3f4UKhkOHOtp73Fjs9IvDg 
```
```
{
    "alg": "RS256", 
    "x5u": "https://esa.hr-link.ru/certificate" 
}
```
``` 
{
    "iss": "esa.hr-link.ru", 
    "sub": "557e5af4-4e53-473d-9a9d-76b69f3823c2", 
    "aud": "company.hr-link.ru", 
    "exp": 1650003600, 
    "nbf": 1650000000, 
    "iat": 1650000000, 
    "jti": "d0fe7aae-9b9c-4964-ab17-af852eb3095b" 
}
```

Использование мастер-токена

Теперь Интегратор может использовать мастер-токен для аутентификации запросов в HRlink от имени пользователей, принадлежащих тенанту Интегратора. Мастер-токен позволяет выполнять вызовы любых API методов, требующих аутентификации пользователя в HRlink.

Для этого в каждом запросе Интегратора в HRlink используются HTTP-заголовки:

``` 
Master-Api-Token: <token>
Impersonated-User-Id: <user_id>
Impersonated-User-Id-Type: HR_LINK_ID | EXTERNAL_ID | SNILS
Impersonated-User-Id-External-System-Type: <external_system_type_name>
```

Master-Api-Token - мастер-токен, полученный Интегратором. 

  • Обязательный для указания.
  • Формат: JWT-токен.

Impersonated-User-Id - ID пользователя, из-под которого выполняется запрос.

  • Обязательный для указания.
  • Формат: строка или UUID.
  • Может быть одного из типов:
    • Внутренний ID пользователя в HRlink. Формат: UUID.
    • ID пользователя HRlink во внешней системе. Формат: строка.
    • СНИЛС физлица пользователя. Формат: строка из 11 цифр подряд, без других символов.

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-External-System-Type - Тип внешней системы, для которой указан ID пользователя, из-под которого выполняется запрос.

  • Необязательный для указания.
  • Формат: строка.
  • Учитывается, если тип ID пользователя Impersonated-User-Id-Type, из-под которого выполняется запрос, указан как EXTERNAL_ID.
  • При задании поиск пользователя будет осуществляться по парам значений ID пользователя во внешней системе и типа системы, переданных в массиве userExternalIds при создании физлица.

Примеры использования

Выполним запрос Получение текущего пользователя с использованием мастер-токена, указав ID пользователя в HRlink.

GET https://company.hr-link.ru/api/v1/currentUser

В HTTP-заголовках запроса укажем:

``` 
Master-Api-Token: qs...rx
Impersonated-User-Id: cdc801a9-12b6-473f-8c66-cdd9b7f0594d
```

Если использован корректный мастер-токен, выданный Интегратору с тенантом company.hr-link.ru и в HRlink существует пользователь этого тенанта с указанным внутренним ID HRlink, то в ответ будут получены данные этого пользователя:

``` 
{
  "result": true,
  "currentUser": {
    "id": "cdc801a9-12b6-473f-8c66-cdd9b7f0594d",
    "uin": "111-111-111",
    "email": "aa@aa.aa",
    "lastName": "A",
    "firstName": "AA",
    "patronymic": "AAA",
    "clients": [...],
    "clientUserIds": [...],
    "employees": [...],
    ...
  }
}
```

Выполним запрос Метод создания отдела клиента с использованием мастер-токена, указав СНИЛС физлица пользователя, от имени которого будет выполнен запрос

``` 
POST https://company.hr-link.ru/api/v1/clients/c42fcc38-998e-48b0-b0c0-818eaaf6ada7/departments
Content-Type: application/json
{
  "parentDepartmentId": "bc2d78c2-765d-4d55-82e7-d683b9a2e4d1",
  "name": "Тестовый отдел"
}
```

 В HTTP-заголовках запроса укажем:

``` 
Master-Api-Token: qs...rx
Impersonated-User-Id: 11896485005
Impersonated-User-Id-Type: SNILS
```

Если использован корректный мастер-токен, выданный Интегратору с тенантом company.hr-link.ru и в HRlink существует пользователь этого тенанта с документом физлица типа СНИЛС с заданным номером 11896485005, и запрос проходит необходимые валидации, то будет выполнено создание отдела и получен ответ:

``` 
{
  "result": true,
  "clientDepartment": {
    "id": "98b35d82-7a7e-4fe5-a4b2-9e9974a5a134",
    "parentDepartmentId": "bc2d78c2-765d-4d55-82e7-d683b9a2e4d1",
    "name": "Тестовый отдел",
    "externalId": null,
    "version": 1
  }
}
```

Выполним запрос Загрузка файлов с использованием мастер-токена, указав ID пользователя во внешней системе.

``` 
POST https://company.hr-link.ru/api/v1/files
Content-Type: multipart/form-data
<Заявление.docx>
```

В HTTP-заголовках запроса укажем:

``` 
Master-Api-Token: qs...rx
Impersonated-User-Id: ext_753
Impersonated-User-Id-Type: EXTERNAL_ID
```

Если использован корректный мастер-токен, выданный Интегратору с тенантом company.hr-link.ru и в HRlink существует пользователь этого тенанта с указанным external_id = ext_753, заданным при создании физлица, и запрос проходит необходимые валидации, то файл будет загружен в HRlink и будет получен ответ:

``` 
{
  "result": true,
  "files": [
    {
      "id": "3236d9e9-a6ef-4957-ba56-072fe56e2737",
      "name": "Заявление.docx",
      "createdDate": "2022-05-26T08:08:36.039568Z"
    }
  ]
}
```

Выполним запрос Создание группы заявлений с использованием мастер-токена, указав ID пользователя во внешней системе заданного типа. Группа заявлений будет создана от имени заданного пользователя.

``` 
POST https://company.hr-link.ru/api/v1/clients/c42fcc38-998e-48b0-b0c0-818eaaf6ada7/applicationGroups
Content-Type: application/json
{
  "date": "2022-05-26",
  "number": "80",
  "typeId": "6bee04bd-2eca-4566-8c4e-8406666fb561",
  "applications": [{
    "legalEntityId": "0e7a76e9-db66-4d61-a00b-5ba53329cb27",
    "employeeId": "b95d546f-63a7-4103-ab50-d1c5d01a16ba",
    "fileId": "3236d9e9-a6ef-4957-ba56-072fe56e2737",
    "employeeApproverId": "7813a047-704e-470d-935b-2733ae9c4e7c"
  }]
}
```

В HTTP-заголовках запроса укажем:

``` 
Master-Api-Token: qs...rx
Impersonated-User-Id: 38475734
Impersonated-User-Id-Type: EXTERNAL_ID
Impersonated-User-Id-External-System-Type: ADFS
```

Если использован корректный мастер-токен, выданный Интегратору с тенантом company.hr-link.ru, в HRlink у этого тенанта зарегистрирована внешняя система с типом ADFS, и существует пользователь с внешним ID со значением value = 38475734, привязанным к внешней системе ADFS, заданным при создании физлица, и запрос проходит необходимые валидации, то от имени сотрудника заданного пользователя будет создана группа заявлений и получен ответ:

``` 
{
  "result": true,
  "applicationGroup": {
    "id": "2020843f-6caf-4830-92c5-98affc267387",
    "creator": {
      "id": "8fa4c849-1ba3-4537-896a-ba79caf1e3ef",
      "lastName" :"ААА",
      "firstName": "АА",
      "patronymic": "А"
    },
    "applicationType": {
      "id": "6bee04bd-2eca-4566-8c4e-8406666fb561",
      "name": "Заявление из файла"
    },
    "date": "2022-05-26",
    "number": "80",
    "externalId": null,
    "signedDate": null,
    "convertedDate": null,
    "applications": [ ... ],
    "createdDate": "2022-05-26T08:08:36.086708Z"
  }
}
```



Сквозная аутентификация

Редирект со сквозной аутентификацией

Метод принимает на вход jwt-токен аутентификации пользователя, сгенерированный интегратором. Производит аутентификацию данного запроса, и в случае успешной аутентификации, делает редирект пользователя в систему HRlink.

Метод

GET https://esa.hr-link.ru/redirect?code={{jwt-token}}&path={{url-encoded-path-value}}&type=PASS_THROUGH_AUTH

Параметры запроса

  • code - в данном параметре должен быть передан сформированный по правилам описанным в пункте 2 jwt-токен

  • path -  в данном параметре должны быть передан путь в системе HRlink, куда должен попасть пользователь. 

    • Например, это может быть страница реестра документов, реестра заявлений, страница какого-то конкретного документа, страница какого-то конкретного заявления и т.д. 

    • Значение должно быть в кодировке URL encoding, чтобы символы пути можно было безопасно использовать в качестве значения query-параметра. В значение пути не должен входить хост! 

    • Пример значения для перехода на страницу документа сотрудника (не в URL encoding): /employee/documents/1df91be9-cbda-459a-948b-e2b8884e5347

  • type - имеет константное значение PASS_THROUGH_AUTH. Данный тип редиректа указывает на то, что выполняется сквозная аутентификация пользователя, которая позволяет пользователю переходить из внешних систем без необходимости вводить логин/пароль для работы в HRlink.

Формирование токена для сквозной аутентификации

Для использования метода сквозной аутентификации интегратору необходимо сформировать специальный jwt-токен который будет передан в параметре code

Тип токена: JWT.

Поля заголовка (header) токена:

  • alg - Алгоритм подписи токена: RS256 или RS384 или RS512. Токен подписан ключом, соответствующим сертификату Интегратора, который был предоставлен Интегратором при регистрации.

Поля тела (payload) токена:

  • iss - Issuer - Издатель jwt-токена. Значение должно быть предоставлено Интегратором при регистрации.

    • Тип: string.

    • Формат: строка.

    • Обязательное: Да

  • sub - Subject - ID Интегратора в ЕСА, который был получен Интегратором после регистрации.

    • Тип: string.

    • Формат: UUID.

    • Обязательное: Да

  • aud - Audience - Хост ЕСА, равный esa.hr-link.ru.

    • Тип: string.

    • Формат: строка.

    • Обязательное: Да

  • thn - Tenant Host Name - Хост тенанта, на который необходимо направить пользователя. Необязательный параметр, если ЕСА сам в состоянии определить в какой тенант нужно направить пользователя.

    • Тип: string.

    • Формат: строка.

    • Обязательное: Нет

  • exp - Expiration Time - Момент времени, когда истекает время действия токена.

    • Тип: number.

    • Формат: Unix Time, количество секунд.

    • Обязательное: Да

  • nbf - Not Before - Момент времени, когда начинается время действия токена.

    • Тип: number.

    • Формат: Unix Time, количество секунд.

    • Обязательное: Да

  • iat - Issued at - Момент времени, когда токен был выдан.

    • Тип: number.

    • Формат: Unix Time, количество секунд.

    • Обязательное: Да

  • uid - User Id - значение идентификатора пользователя.

    • Тип: string

    • Формат: строка или UUID

    • Обязательное: Да

  • uit - User Id Type - тип идентификатора пользователя: должно принимать одно из следующих значений:

    • Тип: string.

    • Формат: строка.

    • Обязательное: Да

    • Возможные значения:

      • HR_LINK_ID - значение в uid - User Id воспринимается как ID пользователя внутри HR-Link.

      • SNILS - значение в uid - User Id воспринимается как СНИЛС физлица пользователя.

      • EXTERNAL_ID - значение в uid - User Id  воспринимается как значение ID пользователя во внешней системе. Поиск пользователя по ID из внешней системы может происходить по-разному, в зависимости от наличия и значения поля est - External System Type.

        • Если est - External System Type не задан или пустой, то выполняется поиск по ID пользователя клиента во внешней системе, указанному при создании физлица в поле externalId (см. Метод создания физлица).

        • Если est - External System Type задан, то выполняется поиск по ID пользователя во внешней системе с заданным типом, указанных при создании физлица в массиве userExternalIds в одном из объектов в полях systemType и value соответственно (см. Метод создания физлица).

    • Если тип не задан, то значение по умолчанию считается HR_LINK_ID.

  • est - External System Type - тип внешней системы, для которой предоставлен идентификатор пользователя.

    • Тип: string.

    • Формат: строка.

    • Обязательное: нет

    • Учитывается, если тип ID пользователя uit - User Id Type, из-под которого выполняется запрос, указан как EXTERNAL_ID.

    • При задании поиск пользователя будет осуществляться по парам значений ID пользователя во внешней системе и типа системы, переданных в массиве userExternalIds при создании физлица.

Поля uid, uit и est необходимы для идентификации пользователя в системе HR-Link.

Время жизни Bearer-токена (exp - nbf) не должно превышать 10 минут. Если требуется изменить это ограничение, обратитесь в службу заботы о клиентах HR-Link.

``` 
{
    "alg": "RS256" | "RS384" | "RS512" 
}
```
```
{
    "iss": "Apple", 
    "sub": "0e7a2d3d-db57-4392-84eb-15083790187d", 
    "aud": "esa.hr-link.ru", 
    "tnh": "some.tenant.com", 
    "uid": "041eded5-e08e-49d9-8161-e77005322ac3", 
    "uit": "HR_LINK_ID", 
    "exp": 1650000600, 
    "nbf": 1650000000, 
    "iat": 1650000000 
}
```
```
eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJBcHBsZSIsInN1YiI6IjBlN2EyZDNkLWRiNTctNDM5Mi04NGViLTE1MDgzNzkwMTg3ZCIsImF1ZCI6ImVzYS5oci1saW5rLnJ1IiwidG5oIjoic29tZS50ZW5hbnQuY29tIiwidWlkIjoiMDQxZWRlZDUtZTA4ZS00OWQ5LTgxNjEtZTc3MDA1MzIyYWMzIiwidWl0IjoiSFJfTElOS19JRCIsImV4cCI6MTY1MDAwMDYwMCwibmJmIjoxNjUwMDAwMDAwLCJpYXQiOjE2NTAwMDAwMDB9.rqiGJbX_R0e7DeoLGFwNaxmdoOgAp0h6ot3wXAmrVlBUwAT0WqceLSSVC0p3McCjNqIuxGuRCUsUvsS-7c0hjhlFYRU-6ywm8uh3qMpUhIJqFXbdpjz3G2IMzdTj3UGLz4xFrn-1lhUNNXiEM5xlpkA188Bb6qoTDp-TL1R-A0Qs5Ma-ZawjB3jq_TOXud2LT_-0iH5E4i405DgtkB56VodVkFfPSUNVbN9azfDngymiWbB4-fi57gVVLS6t2wwYOQums8I1MfbdXlkTIQID-XrVvd3MEU-7o5dJNKPIb3M4E_w29qLReNe9MZjHPl5V-675u16X3GCzIAdH6DQ9Fw 
```

При обращении к API будут произведены проверки аутентификации и валидации. Если какая-либо из проверок не была пройдена, будет возвращена формализованная ошибка.

Аутентификации метода:

  • Параметр code задан (51.215)

  • Параметр code является JWT-токеном (51.202)

  • Алгоритм подписи токена поддерживается системой (51.214)

  • Заданы обязательные поля токена (51.206)

  • Интегратор был зарегистрирован и для него существуют все необходимые настройки (51.250, 51.251)

  • Токен должен был подписан сертификатом, привязанным к интегратору (51.207)

Валидации метода:

  • Параметр path задан 51.215

  • Параметр type задан и является PASS_THROUGH_AUTH (51.154)

  • Поле uit задано (51.206)

  • Поле uit имеет одно из допустимых значений HR_LINK_ID, EXTERNAL_ID, SNILS (51.211)

  • Поле uid соответствует формату UUID или строке (51.206)

  • Поля uid, uit и est (если указано) заданы корректно, в соответствии с возможными принимаемыми значениями (см описание возможных значениий ссылка)

  • Если указано значение thn, тенант с таким хостом существует (51.300)

    • Интегратор имеет право работать с заданным тенантом (51.253)

Результаты работы метода:

При успешном прохождении проверок аутентификации и валидаций, пользователь будет аутентифицирован в системе HR-Link и направлен на страницу, путь которой был указан в параметре path.


Сквозная аутентификация позволяет встраивать приложение HRlink в сторонние приложения клиентов, для того чтобы они могли “бесшовно” (без дополнительной авторизации в HRlink) использовать и открывать его в своих системах.

К примеру, с помощью сквозной аутентификации клиенты смогут открывать приложение HRlink уже будучи авторизованными в мобильном приложении в webview компоненте, либо в браузере через компонент iframe.

Использование сквозной аутентификации

Для использования сквозной аутентификации необходимо:

  1. Пройти первоначальные шаги регистрации в качестве интегратора (см. Регистрация Интегратора в HRlink)

  2. Сформировать jwt-токен по инструкции см пункт (Редирект со сквозной аутентификацией, Формирование токена для сквозной аутентификации)

  3. Сформировать специальную ссылку для редиректа пользователя со сквозной аутентификацией (см. Формирование токена для сквозной аутентификации)

``` 
https://esa.hr-link.ru/redirect?code=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJDbw&path=%2Femployee%2Fdocuments%2F1df9be9-cbda-459a-948b-e2b8884e5347%0A&type=PASS_THROUGH_AUTH 
```

Итоговую полученную ссылку необходимо использовать в системе для перехода в приложение HRlink (вставить её для использования в iframe или webview).

После перехода по ссылке у пользователя откроется страница приложения HRlink (в зависимости от того, какое значение было установлено в параметре path, по умолчанию откроется реестр документов)



SSO — single sign-on

Часто у клиента в его информационной системе есть сервис, который является единой точкой входа сотрудников во все сервисы клиента (так называемый SSO — single sign-on). Соответственно, при использовании HRlink клиент хочет использовать уже существующий единый сервис для входа, чтобы сотрудникам, использующим HRlink, не нужно было запоминать отдельный логин и пароль для HRlink.

Чтобы это было возможно необходимо, чтобы три системы, участвующие в процессе, могли идентифицировать пользователя по одному ID. То есть система кадрового учёта, HRlink и сервис аутентификации должны обладать одним ID для идентификации пользователя.

Общий принцип работы

  1. Предусловие. Система кадрового учёта и сторонний сервис аутентификации имеют один и тот же ID пользователя. Этот ID может быть любым уникальным значением, по которому можно идентифицировать пользователя в информационной системе клиента. Например, это может быть логин пользователя в Active Directory, ID физлица в 1C.ЗУП, внутренний корпоративный ID и т.д. Такой ID договоримся называть ID пользователя во внешней системе. Такое состояние двух систем, когда обе системы имеют один и тот же ID пользователя, должно быть достигнуто любым способом доступным клиенту (поток 1 на схеме). HRlink в этом процессе не участвует. 

  2.  HRlink с помощью методов создания и обновления физлица получает из системы кадрового учёта ID пользователя во внешней системе (поток 2 на схеме).

  3. Пользователь выполняет вход в HRlink через сторонний сервис аутентификации (поток 3 на схеме).

  4. В процессе успешного входа сервис аутентификации сообщает HRlink’у ID пользователя во внешней системе. По полученному ID HRlink может идентифицировать пользователя, совершившего вход, сопоставив его с ID, полученным от системы кадрового учёта (поток 4 на схеме).


Для лучшего понимания рассмотрим пример. Допустим, что всем сотрудникам клиента присваивается некий ID в информационной системе клиента, но происходит это только после того, как сотрудник будет трудоустроен. В таком случае получается ситуация, что при подписании первых кадровых документов при трудоустройстве сотрудник ещё не имеет ID во внешней системе, но уже должен подписать документы в HRlink. Получается следующий процесс:

  1. Новый сотрудник заводится в системе кадрового учёта.

  2. Данные сотрудника передаются из системы кадрового учёта в HRlink без информации об ID пользователя во  внешней системе, т.к. его ещё нет.

  3. Для подписания первых кадровых документов сотрудник входит в HRlink через систему аутентификации HRlink.

  4. После трудоустройства сотрудник получает ID в информационной системе клиента.

  5. Этот ID любым доступным для клиента способом попадает и в систему кадрового учёта, и в сервис аутентификации.

  6. Данные сотрудника вновь передаются из системы кадрового учёта в HRlink, но уже с информацией об ID пользователя во  внешней системе.


После этого все последующие кадровые документы сотрудник сможет подписывать в HRlink, выполняя вход через сторонний сервис аутентификации.

Передача ID пользователя во внешней системе в HRlink из системы кадрового учёта

Для передачи ID пользователя во внешней системе используются методы создания и обновления физлица. В теле запроса присутствует следующий массив с данными:

```
{ ..., "userExternalIds": [ { "systemType": "1C_HRM", "value": "12245" } ], ... } 
```

В данном массиве можно передавать множество ID пользователя во внешних системах. В поле systemType указывается тип внешней системы, в поле value указывается значение ID во внешней системе.

Для указания типа внешней системы (поле systemType) в HRlink предусмотрен справочник типов внешних систем, который может настраиваться индивидуально под клиента. Для добавления элементов в этот справочник нужно обратиться к администраторам HRlink. Предустановленными значениями в этом справочнике являются система кадрового учёта 1С.ЗУП с соответствующим значением 1C_HRM и страховой номер индивидуального лицевого cчёта (СНИЛС) с соответствующим значением SNILS.

Существуют следующие ограничения HRlink на значения ID пользователя во внешних системах:

  • Пользователь HRlink может иметь только один ID в определённом типе внешней системы. Т.е. нельзя установить два и более внешних ID для одного пользователя HRlink в одной системе.

  • Значения внешних ID в рамках одной системы должны быть уникальны для всех пользователей HRlink. Т.е. не может быть двух и более одинаковых значений внешнего ID для одной и той же системы, но для разных пользователей HRlink.

Вход в HRlink через сервис аутентификации, работающий по протоколу OpenID Connect

На текущий момент HRlink поддерживает сторонние системы аутентификации, работающие по протоколу OpenID Connect. В процессе входа пользователя через сторонний сервис аутентификации используется Authorization code flow. Сервис аутентификации должен возвращать ID пользователя во внешней системе или в данных access_token, или в данных id_token.

Внесение настроек стороннего сервиса аутентификации выполняется администраторами HRlink по запросу клиента. Для корректной настройки сервиса аутентификации необходимо предоставить администраторам HRlink следующие данные:

  • Название сервиса, которое будет отображаться пользователю на странице входа в HRlink.

  • Пара ключей clientId и clientSecret. Для получения этих ключей администраторы HRlink в свою очередь предоставят необходимые данные для настройки сервиса аутентификации клиента.

  • Хост, на котором расположен сторонний сервис аутентификации.

  • Endpoint для перенаправления пользователя в сторонний сервис аутентификации для выполнения входа.

  • Endpoint для получения токенов.

Информацию о том в каком токене (access_token или id_token) и в каком поле токена сторонняя система аутентификации возвращает ID пользователя во внешней системе.

Поиск документации