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

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

{
    "tenantHost": "somecompany.hr-link.ru" 
} 

Заголовки

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

Валидации

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

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

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

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

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

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

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

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

Ответ

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

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

Пояснения по формированию Bearer-токена для получения мастер-токена

Интегратор вызывает 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 при создании физлица.

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

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.

Метод

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 пользователя во внешней системе.

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