You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

О чём раздел

В данном разделе описывается Единый Сервис Авторизации HRlink


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

Метод

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

-----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, для которого нужно выпустить мастер-токен. Обязательное поле.

Заголовки:

Authorization: Bearer <token>

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

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

Валидации:

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

Ответ:

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

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

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

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

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

Метод

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

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

  • code - в данном параметре должен быть передан сформированный по правилам описанным в пункте 2 jwt-токен
  • path -  в данном параметре должны быть передан путь в системе HR-Link, куда должен попасть пользователь. 
    • Например, это может быть страница реестра документов, реестра заявлений, страница какого-то конкретного документа, страница какого-то конкретного заявления и т.д. 
    • Значение должно быть в кодировке URL encoding, чтобы символы пути можно было безопасно использовать в качестве значения query-параметра. В значение пути не должен входить хост! 
    • Пример значения для перехода на страницу документа сотрудника (не в URL encoding): /employee/documents/1df91be9-cbda-459a-948b-e2b8884e5347
  • type - имеет константное значение PASS_THROUGH_AUTH. Данный тип редиректа указывает на то, что выполняется сквозная аутентификация пользователя, которая позволяет пользователю переходить из внешних систем без необходимости вводить логин/пароль для работы в HR-Link.

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

Для использования метода сквозной аутентификации интегратору необходимо сформировать специальный 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.

Пример полей заголовка (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)

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

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


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

  • No labels