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

Метод

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

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

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

Используется для получения мастер-токена Интегратором (см. процесс 2. Использование мастер-токена для интеграции с HR-Link).

Метод

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

Content-Type: application/json

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

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

Заголовки:

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

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

• Единый Сервис Авторизации (ЕСА) - Сервис 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-токен и может использовать его в запросе к ЕСА для получения мастер-токена.

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

Метод

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

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

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

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

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

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

Метод

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

Валидации:

• В HTTP-запросе есть заголовок для аутентификации запроса.
• В заголовке для аутентификации запроса содержится Bearer-токен типа JWT.
• JWT-токен содержит все обязательные данные (см. Получение мастер-токена).
• Существует интегратор с ID, равным Subject токена.
• У интегратора существует сертификат открытого ключа.
• JWT-токен подписан алгоритмом RSA с использованием закрытого ключа, соответствующего сертификату открытого ключа интегратора.
• Токен можно использовать в данный момент времени.
• Поля токена сформированы корректно согласно требованиям (см. Получение мастер-токена).

Ответ:

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

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

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

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

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

Метод

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

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

/api/v1/masterTokens

Content-Type: application/json

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

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

Заголовки

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

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

Валидации

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

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

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

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

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

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

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

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

Ответ

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

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

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

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

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

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

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

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

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

• alg -

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

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

• iss- Issuer - Издатель

  jwt

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

• Тип: string.

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

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

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

• Тип: string.

• Формат: UUID.

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

  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.

Пример полей заголовка (header) токена:

```
{
	"alg": "RS256" | "RS384" | "RS512"
}
```

Пример полей тела (payload) токена:

```
{
	"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
}
```

Пример сформированного jwt-токена:

```
eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJBcHBsZSIsInN1YiI6IjBlN2EyZDNkLWRiNTctNDM5Mi04NGViLTE1MDgzNzkwMTg3ZCIsImF1ZCI6ImVzYS5oci1saW5rLnJ1IiwidG5oIjoic29tZS50ZW5hbnQuY29tIiwidWlkIjoiMDQxZWRlZDUtZTA4ZS00OWQ5LTgxNjEtZTc3MDA1MzIyYWMzIiwidWl0IjoiSFJfTElOS19JRCIsImV4cCI6MTY1MDAwMDYwMCwibmJmIjoxNjUwMDAwMDAwLCJpYXQiOjE2NTAwMDAwMDB9.rqiGJbX_R0e7DeoLGFwNaxmdoOgAp0h6ot3wXAmrVlBUwAT0WqceLSSVC0p3McCjNqIuxGuRCUsUvsS-7c0hjhlFYRU-6ywm8uh3qMpUhIJqFXbdpjz3G2IMzdTj3UGLz4xFrn-1lhUNNXiEM5xlpkA188Bb6qoTDp-TL1R-A0Qs5Ma-ZawjB3jq_TOXud2LT_-0iH5E4i405DgtkB56VodVkFfPSUNVbN9azfDngymiWbB4-fi57gVVLS6t2wwYOQums8I1MfbdXlkTIQID-XrVvd3MEU-7o5dJNKPIb3M4E_w29qLReNe9MZjHPl5V-675u16X3GCzIAdH6DQ9Fw
```

При обращении к API будут произведены проверки аутентификации и валидации. Если какая-либо из проверок не была пройдена, будет возвращена формализованная ошибка (см. Ошибочные ответы от 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)

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

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

Время жизни 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 при создании физлица.

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

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

``` 
{
  "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": "Тестовый отдел"
}
```

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

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

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

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

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

``` 
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"
  }]
}
```

``` 
Master-Api-Token: qs...rx
Impersonated-User-Id: 38475734
Impersonated-User-Id-Type: EXTERNAL_ID
Impersonated-User-Id-External-System-Type: 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.

Метод

GEThttps://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 пользователя во внешней системеПри успешном прохождении проверок аутентификации и валидаций, пользователь будет аутентифицирован в системе HR-Link и направлен на страницу, путь которой был указан в параметре path.

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