Российские OAuth провайдеры

ℹ️ О разделе

В этом разделе описывается настройка и использование российских OAuth провайдеров для аутентификации пользователей: Сбер ID, ЕСИА (Госуслуги), Яндекс ID и VK ID. Эти методы позволяют пользователям входить в систему с помощью существующих учетных записей в популярных российских сервисах.

Обзор российских OAuth провайдеров

IDENTYX поддерживает интеграцию со следующими российскими OAuth провайдерами:

🟢 Сбер ID

Аутентификация через экосистему Сбербанка. Требует настройку сертификатов для обеспечения безопасности взаимодействия.

🏛️ ЕСИА (Госуслуги)

Аутентификация через Единую систему идентификации и аутентификации (Госуслуги). Требует электронную подпись для подписи запросов.

🔴 Яндекс ID

Аутентификация через учетную запись Яндекса. Простая настройка через client_id и client_secret.

🔵 VK ID

Аутентификация через учетную запись ВКонтакте. Простая настройка через client_id и client_secret.

Настройка Сбер ID

Требования

Для работы с Сбер ID вам потребуется:

  • Зарегистрированное приложение в Сбер ID
  • Client ID от Сбербанка
  • Client Secret от Сбербанка
  • Сертификат клиента для взаимодействия с API
  • Закрытый ключ сертификата
  • Цепочка сертификатов сервера Сбер ID (сертификат Минцифры)

Настройка в IDENTYX

Для настройки Сбер ID выполните следующие шаги:

  1. Перейдите в раздел Настройки → Настройки
  2. Раскройте раздел Авторизация → Сбер ID
  3. Установите флажок Включить аутентификацию через Сбер ID
  4. Заполните поле client_id — идентификатор вашего приложения, полученный от Сбербанка
  5. Заполните поле redirect_uri — URL для перенаправления после аутентификации (должен заканчиваться на /login/sber, например: https://mysite.local/login/sber)
  6. Заполните поле client_secret — секретный ключ приложения
  7. Загрузите сертификаты:
    • Нажмите кнопку Сертификат и загрузите сертификат клиента
    • Нажмите кнопку Закрытый ключ и загрузите закрытый ключ сертификата
    • Нажмите кнопку Цепочка сертификатов сервера Сбер ID и загрузите цепочку сертификатов (один файл PEM с несколькими сертификатами)
  8. Нажмите кнопку Сохранить внизу страницы
⚠️ Важно

Цепочка сертификатов сервера Сбер ID должна быть представлена одним файлом в формате PEM, содержащим всю цепочку сертификатов от сервиса Сбер ID.

Автоматическая регистрация через Сбер ID

Вы можете настроить автоматическое создание учетных записей при первом входе через Сбер ID:

  1. В разделе Сбер ID установите флажок Разрешить регистрировать учетные записи через Сбер ID
  2. В поле Группа для автоматической регистрации через Сбер ID выберите группы, в которые будут автоматически добавляться новые пользователи
  3. Сохраните настройки

При автоматической регистрации:

  • Автоматически создается локальная учетная запись в IDENTYX
  • Отображаемое имя формируется из данных Сбер ID (фамилия, имя, отчество)
  • Пользователь добавляется в указанные группы
  • Пользователь может быть добавлен в организации (если настроено)
  • Все действия логируются в журнал событий

Настройка ЕСИА (Госуслуги)

Требования

Для работы с ЕСИА вам потребуется:

  • Зарегистрированная информационная система в ЕСИА
  • Client ID (мнемоника системы)
  • Сертификат электронной подписи, установленный на сервере
  • Отпечаток (thumbprint) сертификата
  • Пин-код от токена (если используется)

Настройка в IDENTYX

Для настройки ЕСИА выполните следующие шаги:

  1. Перейдите в раздел Настройки → Настройки
  2. Раскройте раздел Авторизация → ЕСИА (Госуслуги)
  3. Установите флажок Включить аутентификацию через ЕСИА
  4. Заполните поле client_id — мнемоника вашей информационной системы
  5. Заполните поле Сертификат для подписи запросов — отпечаток (thumbprint) сертификата, установленного на сервере
  6. Заполните поле Пин-код от токена для подписи запросов — оставьте пустым, если контейнер не требует пин-кода
  7. Заполните поле redirect_uri — URL для перенаправления (должен заканчиваться на /login/esia, например: https://mysite.local/login/esia)
  8. Нажмите кнопку Сохранить
ℹ️ Электронная подпись

IDENTYX использует КриптоПро для подписи запросов к ЕСИА. Сертификат должен быть установлен на сервере, где развернут IDENTYX, и доступен для процесса веб-сервера.

Автоматическая регистрация через ЕСИА

Настройка автоматической регистрации через ЕСИА аналогична Сбер ID:

  1. Установите флажок Разрешить регистрировать учетные записи через ЕСИА
  2. В поле Группа для автоматической регистрации через ЕСИА выберите нужные группы
  3. Сохраните настройки

При автоматической регистрации отображаемое имя формируется из данных ЕСИА (фамилия, имя, отчество).

Настройка Яндекс ID

Требования

Для работы с Яндекс ID вам потребуется:

  • Зарегистрированное OAuth-приложение на oauth.yandex.ru
  • Client ID приложения
  • Client Secret приложения

Настройка в IDENTYX

Для настройки Яндекс ID выполните следующие шаги:

  1. Перейдите в раздел Настройки → Настройки
  2. Раскройте раздел Авторизация → Яндекс ID
  3. Установите флажок Включить аутентификацию через Яндекс
  4. Заполните поле client_id — идентификатор вашего приложения
  5. Заполните поле client_secret — секретный ключ приложения
  6. Нажмите кнопку Сохранить
✅ Простота настройки

Яндекс ID не требует дополнительных сертификатов или сложной настройки — достаточно только client_id и client_secret из личного кабинета Яндекс OAuth.

Автоматическая регистрация через Яндекс ID

  1. Установите флажок Разрешить регистрировать учетные записи через Яндекс
  2. В поле Группа для автоматической регистрации через Яндекс выберите нужные группы
  3. Сохраните настройки

При автоматической регистрации отображаемое имя берется из профиля Яндекса (display_name).

Настройка VK ID

Требования

Для работы с VK ID вам потребуется:

  • Зарегистрированное приложение ВКонтакте
  • Client ID приложения
  • Client Secret приложения

Настройка в IDENTYX

Для настройки VK ID выполните следующие шаги:

  1. Перейдите в раздел Настройки → Настройки
  2. Раскройте раздел Авторизация → VK
  3. Установите флажок Включить аутентификацию через VK
  4. Заполните поле client_id — идентификатор вашего приложения
  5. Заполните поле redirect_uri — URL для перенаправления (должен заканчиваться на /login/vk, например: https://mysite.local/login/vk)
  6. Заполните поле client_secret — секретный ключ приложения
  7. Нажмите кнопку Сохранить

Автоматическая регистрация через VK ID

  1. Установите флажок Разрешить регистрировать учетные записи через VK
  2. В поле Группа для автоматической регистрации через VK выберите нужные группы
  3. Сохраните настройки

При автоматической регистрации отображаемое имя формируется из данных профиля VK (фамилия и имя).

Вход пользователей через OAuth провайдеры

После настройки OAuth провайдеров на странице входа в систему появятся соответствующие кнопки:

  • Кнопка с логотипом Сбербанка — для входа через Сбер ID
  • Кнопка с логотипом Госуслуг — для входа через ЕСИА
  • Кнопка с логотипом Яндекса — для входа через Яндекс ID
  • Кнопка с логотипом ВКонтакте — для входа через VK ID

Процесс входа

Когда пользователь нажимает на одну из кнопок OAuth провайдера:

  1. Пользователь перенаправляется на страницу входа выбранного провайдера
  2. Пользователь вводит свои учетные данные на стороне провайдера
  3. После успешной аутентификации провайдер перенаправляет пользователя обратно в IDENTYX
  4. IDENTYX проверяет пользователя:
    • Если учетная запись уже привязана — пользователь входит в систему
    • Если автоматическая регистрация включена — создается новая учетная запись и пользователь входит
    • Если автоматическая регистрация выключена — отображается сообщение об отсутствии учетной записи
ℹ️ Журналирование

Все попытки входа через OAuth провайдеры, как успешные, так и неудачные, фиксируются в журнале событий безопасности с указанием типа провайдера и идентификатора пользователя.

Привязка OAuth провайдеров к существующим аккаунтам

Пользователи могут привязать OAuth провайдеров к своей учетной записи в профиле:

  1. Войдите в систему под своей учетной записью
  2. Перейдите в Профиль пользователя
  3. В разделе методов аутентификации найдите нужный OAuth провайдер
  4. Нажмите кнопку для привязки (например, кнопку с логотипом Сбера)
  5. Выполните аутентификацию на стороне провайдера
  6. После успешной аутентификации внешняя учетная запись будет привязана
⚠️ Уникальность привязки

Одна учетная запись OAuth провайдера может быть привязана только к одному пользователю в IDENTYX. При попытке привязать уже используемый аккаунт система выдаст ошибку.

Отвязка OAuth провайдеров

Для отвязки OAuth провайдера:

  1. Перейдите в Профиль пользователя
  2. Найдите привязанный метод аутентификации
  3. Нажмите кнопку отвязки рядом с провайдером
  4. Подтвердите действие

Управление правами входа

Администратор может разрешить или запретить отдельному пользователю входить через конкретный OAuth провайдер:

  1. Перейдите в раздел Пользователи → Локальные пользователи
  2. Откройте карточку пользователя
  3. В разделе методов аутентификации найдите нужный провайдер
  4. Установите или снимите флажок разрешения входа через этот провайдер
  5. Сохраните изменения
🚫 Важно

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

Автоматическое добавление в группы и организации

Для всех OAuth провайдеров поддерживается автоматическое добавление новых пользователей в группы и организации:

Добавление в группы

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

Добавление в организации

Аналогично можно настроить автоматическое добавление в организации. Это настраивается через параметры системы (например, sber_auto_reg_orgs, esia_auto_reg_orgs и т.д.).

ℹ️ Применение при регистрации

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

Безопасность и журналирование

Функции безопасности

  • HTTPS обязателен — все взаимодействие с OAuth провайдерами происходит только по защищенному протоколу
  • Проверка подписей — для Сбер ID используется проверка JWT токенов с помощью client_secret
  • Электронная подпись — для ЕСИА все запросы подписываются электронной подписью
  • State parameter — используется для защиты от CSRF атак
  • Nonce — используется для защиты от replay атак

Журналирование событий

В журнале событий фиксируются:

  • Успешная аутентификация через OAuth провайдер
  • Неудачная аутентификация
  • Привязка OAuth провайдера к учетной записи
  • Отвязка OAuth провайдера
  • Автоматическое создание учетной записи
  • Автоматическое добавление в группы
  • Автоматическое добавление в организации
  • Отказ в аутентификации (заблокированная учетная запись, запрет входа через провайдер)

Решение проблем

Частые проблемы

Проблема Возможная причина Решение
Кнопка провайдера не отображается на странице входа Провайдер не включен в настройках Убедитесь, что флажок "Включить аутентификацию через..." установлен и настройки сохранены
Ошибка "Нет ответа от OIDC сервера" Проблемы с сетевым подключением или неверные сертификаты (для Сбер ID) Проверьте подключение к интернету и правильность загруженных сертификатов
Ошибка "Учетная запись уже привязана" OAuth аккаунт уже используется другим пользователем Сначала отвяжите аккаунт от другого пользователя или используйте другой OAuth аккаунт
Ошибка "В аутентификации пользователя отказано" Пользователю запрещен вход через этот провайдер Проверьте настройки пользователя и убедитесь, что вход через провайдер разрешен
Автоматическая регистрация не работает Автоматическая регистрация отключена Включите флажок "Разрешить регистрировать учетные записи через..." в настройках провайдера

Проблемы с сертификатами Сбер ID

Если возникают ошибки при работе с Сбер ID:

  1. Убедитесь, что загружены все три файла: сертификат клиента, закрытый ключ и цепочка сертификатов сервера
  2. Проверьте, что цепочка сертификатов содержит все необходимые сертификаты в формате PEM
  3. Проверьте срок действия сертификатов
  4. Убедитесь, что закрытый ключ соответствует загруженному сертификату

Проблемы с подписью ЕСИА

Если возникают ошибки при работе с ЕСИА:

  1. Убедитесь, что КриптоПро установлен на сервере
  2. Проверьте, что сертификат установлен в хранилище и доступен для процесса веб-сервера
  3. Убедитесь, что отпечаток (thumbprint) указан правильно
  4. Если используется токен с пин-кодом, убедитесь, что пин-код указан верно
  5. Проверьте журнал системы на наличие ошибок подписи
✅ Готовы продолжить?

Переходите к разделу Telegram аутентификация для изучения настройки входа через Telegram.