Корпоративный SSO через OpenID Connect

При корпоративном SSO сотрудник входит в HRlink через провайдера удостоверений компании (IdP). На странице HRlink он выбирает корпоративный вход, проходит аутентификацию на стороне IdP и возвращается в HRlink без отдельного ввода пароля.

HRlink использует поток OAuth 2.0 Authorization Code. После входа HRlink получает id_token или JWT access_token, извлекает из него внешний идентификатор и находит существующую учётную запись HRlink.

SSO отвечает только за вход. Роли и доступные сотруднику данные в HRlink не меняются.

Как проходит вход

Сотрудник открывает страницу входа HRlink и выбирает корпоративный SSO.
HRlink перенаправляет браузер на страницу входа IdP.
IdP аутентифицирует сотрудника, возвращает его браузер в HRlink и передаёт одноразовый код авторизации.
Сервер HRlink обменивает код на токены.
HRlink берёт из настроенного токена внешний идентификатор и находит связанную с ним учётную запись.
Если учётная запись подтверждена и не отключена, HRlink открывает пользовательскую сессию.

HRlink добавляет к запросу случайный параметр state. Он связывает начало входа с возвратом от IdP и защищает запрос от повторной обработки.

Что проверить до подключения

IdP должен поддерживать:

OAuth 2.0 Authorization Code;
конфиденциальный веб-клиент с client_id и client_secret;
передачу client_secret в теле запроса к адресу получения токенов в формате application/x-www-form-urlencoded;
HTTPS для страницы входа и адреса получения токенов;
возврат id_token или JWT access_token с уникальным идентификатором сотрудника.

HRlink не загружает конфигурацию из /.well-known/openid-configuration. Все параметры и поле внешнего идентификатора настраивает техническая поддержка HRlink.

Проверьте и сетевую доступность:

страница входа IdP должна открываться в браузерах сотрудников;
адрес получения токенов должен быть доступен из инфраструктуры облачного HRlink или с серверов On-premises HRlink;
сервер HRlink должен доверять TLS-сертификату IdP.

Если IdP работает только во внутренней сети, подготовьте сетевой маршрут до отправки заявки. HRlink не подключается к адресам по HTTP и к серверам с недействительным TLS-сертификатом.

Со стороны клиента в подключении участвуют администратор IdP и техподдержка HRlink. Администратор IdP регистрирует приложение и готовит его параметры. Администратор HRlink проверяет учётные записи сотрудников и их внешние идентификаторы. Инженер HRlink настраивает подключение по данным из заявки.

1. Зарегистрируйте приложение в IdP

Создайте для HRlink отдельный конфиденциальный веб-клиент. Не используйте client_id и секрет другого сервиса.

Разрешите поток Authorization Code и добавьте адрес возврата:

https://{tenantHost}/api/v1/idp/oidc/callback

tenantHost — адрес тенанта HRlink, например company.hr-link.ru. Адрес возврата должен совпадать полностью: схема https, hostname и путь без завершающего /.

Если у компании несколько тенантов с разными адресами, добавьте адрес возврата каждого тенанта или создайте отдельное приложение для каждого из них.

Запишите параметры, которые IdP требует при переходе на страницу входа. Например:

scope=openid%20profile%20email

Передавайте их как готовую строку без начальных ? и &. Пробелы и специальные символы должны быть закодированы как в URL. Не добавляйте client_id, response_type, state и redirect_uri: HRlink формирует их сам.

Если сотрудники используют мобильное приложение HRlink, проверьте, требует ли IdP дополнительных query-параметров для входа из приложения. Если не требует, укажите в заявке «Не нужны». Отдельный адрес возврата для мобильного приложения регистрировать не нужно.

2. Выберите внешний идентификатор

HRlink сопоставляет учётные записи по одному полю верхнего уровня из id_token или JWT access_token. Выберите поле, которое:

присутствует при каждом входе;
уникально для сотрудника у выбранного IdP;
не меняется при смене фамилии, email-адреса, подразделения или должности;
содержит строковое значение.

Лучше использовать неизменяемый идентификатор, например sub, если IdP сохраняет его для зарегистрированного приложения. Email и логин подходят только в том случае, если компания не меняет и не назначает их повторно.

Также определите:

источник идентификатора — ID_TOKEN или ACCESS_TOKEN;
точное имя поля;
нужно ли игнорировать регистр при сравнении.

Подготовьте учётные записи HRlink

SSO не создаёт учётные записи и не связывает их автоматически по email-адресу. До первого входа:

создайте для сотрудника учётную запись HRlink;
подтвердите учётную запись;
убедитесь, что учётная запись не отключена;
составьте список соответствий: учётная запись HRlink — внешний идентификатор сотрудника в IdP.

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

Если включено сравнение без учёта регистра, USER-123 и user-123 совпадут. HRlink не удаляет пробелы, не меняет доменную часть и не заменяет символы.

На этом этапе подготовьте список, но не загружайте его. Сначала инженер HRlink настроит подключение и сообщит техническое имя типа внешней системы — значение systemType для API синхронизации.

Режим	Вход через SSO	Вход по паролю HRlink
SSO как дополнительный способ	Доступен при наличии привязки	Доступен
Только SSO для привязанных учётных записей	Доступен при наличии привязки к активному IdP	Заблокирован для привязанных учётных записей
Строгий режим «только SSO»	Доступен при наличии корректной привязки	Заблокирован для всех учётных записей тенанта

Для первого запуска выберите SSO как дополнительный способ. После проверки тестовой группы можно запретить парольный вход для привязанных учётных записей или для всего тенанта.

Строгий режим блокирует парольный вход для всех

Не включайте строгий режим, пока не проверите привязки всех учётных записей, включая учётные записи администраторов. Заранее назначьте ответственного администратора IdP и укажите в заявке, как действовать при недоступности IdP.

4. Отправьте одну заявку на подключение

Создайте одну заявку в Службу заботы. Заявка остаётся открытой до проверки входа и включения выбранного режима. В ней инженер HRlink согласует передачу секрета, сообщит о готовности к тесту и зафиксирует результаты запуска.

Укажите в заявке:

Данные	Что указать	Пример
Адрес тенанта	Hostname HRlink	`company.hr-link.ru`
Название кнопки	Понятное сотрудникам название входа	`Войти через корпоративный SSO`
Адрес IdP	Базовый HTTPS-адрес без пути	`https://login.company.ru`
Страница входа	Путь для авторизации сотрудника	`/oauth2/authorize`
Адрес получения токенов	Путь для обмена кода на токены	`/oauth2/token`
`client_id`	Идентификатор веб-клиента	`hrlink-production`
Параметры входа	Параметры `scope` и другие параметры IdP	`scope=openid%20profile%20email`
Источник идентификатора	Токен с нужным полем	`ID_TOKEN`
Поле идентификатора	Имя поля верхнего уровня в JWT	`sub`
Тип внешней системы	Техническое имя для `userExternalIds[].systemType`	`CORPORATE_SSO`
Сравнение	Нужно ли игнорировать регистр	`Нет`
Параметры для приложения	Дополнительные query-параметры IdP только для входа из мобильного приложения HRlink	Не нужны
Тестовый сотрудник	Учётная запись HRlink и внешний идентификатор в IdP	`ivanov@company.ru`, `00u123abc`
Сеть	VPN, частный DNS, allowlist или корпоративный центр сертификации	Краткое описание доступа
Режим запуска	Начальный и целевой режим входа	Дополнительный, затем только SSO для привязанных учётных записей
Ответственный	Контакт администратора IdP на время запуска	Имя, email и телефон
Откат	Когда вернуть парольный вход при ошибке	Если SSO недоступен более 15 минут

Не прикладывайте client_secret к заявке. Инженер HRlink подтвердит адрес возврата и предложит защищённый канал для передачи секрета в той же переписке. HRlink хранит секрет в зашифрованном виде.

После получения данных инженер HRlink:

настраивает подключение к IdP;
создаёт тип внешней системы и привязывает тестовую учётную запись;
сообщает в заявке значение systemType и готовность к проверке;
после проверки включает целевой режим в согласованное время.

5. Проверьте подключение и добавьте привязки

Проверьте тестовую учётную запись

Когда инженер HRlink сообщит о готовности, проверьте:

На странице HRlink есть кнопка с согласованным названием.
Кнопка открывает страницу нужного IdP.
После входа сотрудник возвращается в тот же тенант HRlink.
Тестовый сотрудник входит в свою учётную запись.
Роли и доступные данные не отличаются от входа по паролю.
Сотрудник без привязки не входит под чужой учётной записью.
Отключённая или неподтверждённая учётная запись не получает доступ.
Если сотрудники используют мобильное приложение HRlink, после аутентификации в IdP они возвращаются в приложение и входят в свою учётную запись.
Выход и повторный вход работают с учётом активной сессии IdP.

Добавьте остальные привязки через API

После успешного входа тестового сотрудника добавьте внешние идентификаторы остальных сотрудников. Для массовой загрузки используйте создание задачи синхронизации сотрудников с типом CLIENT_USERS_V6. Ход выполнения и ошибки проверяйте методом получения статуса задачи синхронизации. Полный порядок работы описан в разделе «Синхронизация сотрудников».

Передайте привязку SSO в массиве userExternalIds на уровне учётной записи, а не внутри employees. Публичный API не создаёт тип внешней системы: запрос добавляет сотруднику идентификатор для уже настроенного systemType.

Пример тела запроса:

{
  "type": "CLIENT_USERS_V6",
  "data": [
    {
      "externalId": "USER-001",
      "snils": "12345678901",
      "email": "ivanov@company.ru",
      "surname": "Иванов",
      "name": "Иван",
      "patronymic": "Иванович",
      "userExternalIds": [
        {
          "systemType": "CORPORATE_SSO",
          "value": "00u123abc"
        }
      ],
      "employees": [
        {
          "externalId": "EMP-001",
          "legalEntityExternalId": "LE-001",
          "departmentExternalId": "DEP-IT",
          "positionExternalId": "POS-DEV",
          "isMainWorkplace": true
        }
      ]
    }
  ]
}

В этом примере:

externalId со значением USER-001 связывает учётную запись HRlink с записью в вашей учётной системе. Это не идентификатор для входа по SSO;
systemType должен полностью совпадать с техническим именем из заявки на подключение — в примере это CORPORATE_SSO;
value должен полностью совпадать со значением выбранного поля JWT — в примере поле sub содержит 00u123abc.

Массив userExternalIds задаёт полный набор внешних идентификаторов учётной записи. Если сотрудник уже связан с другими внешними системами, передайте в массиве и существующие привязки, иначе HRlink удалит их.

Для изменения одной существующей учётной записи можно использовать метод обновления пользователя клиента. Он полностью заменяет данные пользователя: передайте все текущие поля и все нужные элементы userExternalIds. Для регулярной интеграции безопаснее использовать задачу синхронизации.

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

Если вход не работает

Если во время проверки возникла ошибка, добавьте в заявку:

Данные	Что указать
Время ошибки	Дата, точное время и часовой пояс
Этап	Нет кнопки, не открывается IdP, ошибка на IdP, ошибка после возврата в HRlink или вход в неверную учётную запись
Ошибка HRlink	`errorId` и `errorCode`, если они показаны
Ошибка IdP	`error` и `error_description`, если они показаны
Сотрудник	Логин в IdP, учётная запись HRlink и ожидаемый внешний идентификатор
Рабочее место	Операционная система, браузер или версия мобильного приложения
Журналы IdP	Correlation ID или фрагмент журнала за время ошибки
Последние изменения	Секрет, адрес возврата, параметры, поле токена, сертификат, DNS или сетевые правила

Укажите, возникает ли ошибка у одного сотрудника или у всех. Для ошибки сопоставления можно приложить названия полей JWT без значений с персональными данными.

Не передавайте пароль, client_secret, код авторизации, id_token, access_token, cookie сессии или полный URL возврата с query-параметрами.

Ограничения

HRlink поддерживает Authorization Code с конфиденциальным клиентом. Подключение без client_secret не поддерживается.
Все адреса IdP должны использовать HTTPS.
HRlink настраивает адреса вручную и не использует OpenID Connect Discovery.
Источником внешнего идентификатора может быть только id_token или JWT access_token. Получение идентификатора из UserInfo endpoint для новых подключений не поддерживается.
Поле внешнего идентификатора должно находиться на верхнем уровне JWT. Путь к вложенному полю указать нельзя.
HRlink не создаёт учётную запись при первом SSO-входе и не связывает её по email, логину или другому полю.
HRlink сравнивает внешние идентификаторы точно, с учётом или без учёта регистра. Других преобразований нет.
PKCE не используется. IdP должен разрешать обмен кода авторизации с client_secret.
HRlink не завершает сессию на стороне IdP. После выхода из HRlink активная сессия IdP может снова пропустить сотрудника без ввода учётных данных.
Для одного тенанта можно настроить несколько активных IdP. Сотрудник выбирает IdP по названию кнопки.
Управлять подключениями к IdP в интерфейсе HRlink нельзя. Настройку и ротацию секрета выполняет инженер HRlink.

Если нужен прозрачный вход с доменного компьютера в On-premises-поставке, используйте интеграцию с Active Directory через Kerberos.

Как проходит вход​

Что проверить до подключения​

1. Зарегистрируйте приложение в IdP​

2. Выберите внешний идентификатор​

Подготовьте учётные записи HRlink​

3. Выберите режим входа​

4. Отправьте одну заявку на подключение​

5. Проверьте подключение и добавьте привязки​

Проверьте тестовую учётную запись​

Добавьте остальные привязки через API​

Если вход не работает​

Ограничения​