OAuth провайдеры

Введение

Системный каталог OAuth провайдеры используется для настройки внешних провайдеров аутентификации, позволяющих пользователям входить в систему Бипиум через учетные записи социальных сетей или корпоративных систем (Google, Yandex, Mail.ru, VK, Keycloak и другие OAuth 2.0 / OpenID Connect провайдеры).

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

Назначение каталога

Каталог OAuth провайдеры используется для:

• Настройки внешней аутентификации: подключение провайдеров OAuth 2.0 / OpenID Connect для входа в систему

• Упрощения входа: пользователи могут входить в систему без создания отдельного аккаунта в Бипиуме

• Интеграции с корпоративными системами: подключение корпоративных систем аутентификации (Keycloak, Active Directory через Keycloak и т.д.)

• Настройки SSO (Single Sign-On): организация единой точки входа для пользователей

• Ограничения доступа: привязка провайдеров к конкретным компаниям в мультидоменной конфигурации

Доступ к каталогу

Каталог OAuth провайдеры находится в разделе Система и доступен только администраторам сервера Бипиум.

Как открыть каталог:

1. Войдите в систему с правами администратора

2. Перейдите в раздел Система (в главном меню)

3. Выберите каталог OAuth провайдеры

Поля каталога

Поля в каталоге отображаются в следующем порядке:

Общие параметры

Поле	Тип	Описание
Активна	Переключатель	Включает или отключает провайдер. Только активные провайдеры отображаются на странице входа
Провайдер	Радиокнопка	Тип провайдера. Доступны: Google, Yandex, Mail.ru, VK, Keycloak, OAuth2. Обязательное поле
ClientID	Текст	Идентификатор клиента (Client ID), полученный при регистрации приложения у провайдера. Обязательное поле
Client secret	Текст	Секретный ключ клиента (Client Secret), полученный при регистрации приложения у провайдера
Порядковый номер в списке	Число	Порядок отображения провайдера в списке на странице входа. Чем меньше число, тем выше провайдер в списке
Компании	Объект (множественный выбор)	Список компаний, для которых доступен этот провайдер. Используется только в мультидоменной конфигурации. Если значение не задано, провайдер доступен всем компаниям

Кнопка (альтернативный вид)

Поле	Тип	Описание
Подпись	Текст	Текст, отображаемый на кнопке входа. Если не указано, используется название провайдера по умолчанию
Иконка	Файл	Изображение иконки для кнопки входа. Если не указано, используется иконка провайдера по умолчанию

Дополнительные настройки

Эти поля отображаются только для провайдеров типа OAuth2 и Keycloak:

Поле	Тип	Описание
Authorization Endpoint	Текст	URL для получения кода подтверждения. Обязательное поле для OAuth2
Token Endpoint	Текст	URL для обмена кода подтверждения на OAuth-токен. Обязательное поле для OAuth2
Userinfo Endpoint	Текст	URL для получения информации о пользователе. Обязательно для заполнения, если провайдер не поддерживает стандарт OpenID Connect
Поле логина	Текст	Название поля в ответе провайдера, содержащего логин пользователя. Для Keycloak по умолчанию используется "preferred_username"
Поле имени пользователя	Текст	Название поля в ответе провайдера, содержащего имя пользователя. Для Keycloak по умолчанию используется "name"
Scope	Текст	Набор scope, разделенный пробелами, для получения информации о пользователе (логин и имя). Если провайдер поддерживает OpenID Connect, добавьте "openid"
Другие параметры	Текст (многострочное)	Дополнительные параметры в формате JSON, необходимые провайдеру. Например, для Keycloak укажите "realmUrl" с URL до сервера с указанием Realm

Важная информация

Как работают OAuth провайдеры?

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

1. Пользователь нажимает кнопку входа через провайдер на странице входа в Бипиум

2. Система перенаправляет пользователя на страницу авторизации провайдера

3. Пользователь авторизуется у провайдера (вводит логин и пароль)

4. Провайдер возвращает код авторизации в Бипиум

5. Бипиум обменивает код на токен и получает информацию о пользователе

6. Пользователь входит в систему — если аккаунт с таким email уже существует, пользователь входит в него; если нет, создается новый аккаунт

Поддерживаемые провайдеры

Предустановленные провайдеры

Система поддерживает следующие типы провайдеров:

1. Google — вход через Google аккаунт

2. Yandex — вход через Yandex ID

3. Mail.ru — вход через Mail.ru ID

4. VK — вход через VK ID

5. Keycloak — вход через Keycloak (для корпоративных систем)

6. OAuth2 — универсальный провайдер для любых OAuth 2.0 / OpenID Connect систем

Различия между провайдерами

• Google, Yandex, Mail.ru, VK: предустановленные настройки, требуется только указать ClientID и Client Secret

• Keycloak: предустановленные настройки для Keycloak, можно дополнительно настроить параметры

• OAuth2: универсальный провайдер, требует указания всех endpoints и параметров вручную

Настройка Redirect URI

При регистрации приложения у провайдера необходимо указать Redirect URI (URI перенаправления):

https://ваш-домен.com/auth/callback

Важно: Замените ваш-домен.com на реальный домен вашего сервера Бипиум. Если используется несколько доменов, добавьте все необходимые URL в настройках приложения у провайдера.

Привязка к компаниям

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

• Если поле "Компании" пустое: провайдер доступен для всех компаний

• Если указаны компании: провайдер доступен только для выбранных компаний

Это позволяет настроить разные провайдеры для разных компаний в одной системе.

Практические сценарии

Важно: Подробные пошаговые инструкции по настройке всех типов провайдеров (Google, Yandex, Mail.ru, VK, Keycloak) см. в документации SSO (Single Sign-On).

Как настроить провайдер в каталоге?

После создания приложения у провайдера и получения Client ID и Client Secret:

1. Откройте каталог OAuth провайдеры в разделе Система

2. Создайте новую запись

3. Заполните основные параметры:

   • Провайдер — выберите тип провайдера (Google, Yandex, Mail.ru, VK, Keycloak, OAuth2)

   • ClientID — укажите Client ID, полученный у провайдера

   • Client secret — укажите Client Secret, полученный у провайдера

   • Активна — включите переключатель

4. Для OAuth2 и Keycloak заполните дополнительные настройки (см. раздел "Дополнительные настройки" выше)

5. Сохраните запись

Примечание: Для получения Client ID и Client Secret, а также подробных инструкций по настройке каждого типа провайдера см. SSO (Single Sign-On).

Как настроить универсальный OAuth2 провайдер?

Для настройки произвольного OAuth 2.0 / OpenID Connect провайдера:

1. Получите информацию о провайдере:

   • URL для авторизации (Authorization Endpoint)

   • URL для получения токена (Token Endpoint)

   • URL для получения информации о пользователе (Userinfo Endpoint), если провайдер не поддерживает OpenID Connect

   • Client ID и Client Secret

   • Необходимые scope для получения информации о пользователе

2. Настройте провайдер в каталоге:

   • Выберите тип провайдера "OAuth2"

   • Заполните обязательные поля: ClientID, Authorization Endpoint, Token Endpoint

   • При необходимости заполните: Userinfo Endpoint, Поле логина, Поле имени пользователя, Scope

   • Включите переключатель Активна и сохраните запись

Как изменить порядок отображения провайдеров?

Для изменения порядка отображения провайдеров на странице входа:

1. Откройте каталог OAuth провайдеры в разделе Система

2. Откройте запись провайдера

3. В поле Порядковый номер в списке укажите число:

   • Меньшие числа отображаются выше в списке

   • Например, провайдер с номером 1 будет первым, с номером 2 — вторым и т.д.

4. Сохраните изменения

Как настроить кастомную иконку и подпись?

Для настройки внешнего вида кнопки входа:

1. Откройте каталог OAuth провайдеры в разделе Система

2. Откройте запись провайдера

3. В разделе Кнопка (альтернативный вид):

   • В поле Подпись укажите текст, который будет отображаться на кнопке

   • В поле Иконка загрузите изображение иконки для кнопки

4. Сохраните изменения

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

Работа с каталогом

Как создать провайдер?

Для создания нового OAuth провайдера:

1. Откройте каталог OAuth провайдеры в разделе Система

2. Создайте новую запись

3. Заполните обязательные поля:

   • Провайдер — выберите тип провайдера

   • ClientID — укажите идентификатор клиента

   • Для OAuth2: Authorization Endpoint и Token Endpoint

4. Заполните дополнительные поля при необходимости

5. Включите переключатель Активна для активации провайдера

6. Сохраните запись

Как отключить провайдер?

Для временного отключения провайдера без удаления:

1. Откройте каталог OAuth провайдеры в разделе Система

2. Найдите запись провайдера

3. Отключите переключатель Активна

4. Сохраните изменения

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

Как удалить провайдер?

Для удаления провайдера:

1. Откройте каталог OAuth провайдеры в разделе Система

2. Найдите запись провайдера

3. Нажмите кнопку удаления записи

4. Подтвердите удаление

Важно: После удаления провайдера пользователи не смогут входить через этот провайдер. Убедитесь, что у пользователей есть альтернативные способы входа.

Как ограничить доступ провайдера для конкретных компаний?

В мультидоменной конфигурации можно ограничить доступ провайдера:

1. Откройте каталог OAuth провайдеры в разделе Система

2. Откройте запись провайдера

3. В поле Компании выберите компании, для которых должен быть доступен этот провайдер

4. Сохраните изменения

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

Технические детали

Структура данных провайдера

Провайдер в системе представлен следующими данными:

• enabled — активен ли провайдер

• type — тип провайдера (google, yandex, mailru, vk, keycloak, oauth)

• clientId — идентификатор клиента

• clientSecret — секретный ключ клиента

• position — порядковый номер для сортировки

• companies — список компаний (для мультидомена)

• label — подпись кнопки

• icon — иконка кнопки

• authorizationEndpoint — URL для авторизации (для OAuth2)

• tokenEndpoint — URL для получения токена (для OAuth2)

• userinfoEndpoint — URL для получения информации о пользователе (для OAuth2)

• userLoginKey — поле логина в ответе провайдера

• userNameKey — поле имени в ответе провайдера

• scope — список scope для запроса

• params — дополнительные параметры в формате JSON

Процесс авторизации

Процесс авторизации через OAuth провайдер:

1. Инициация: пользователь нажимает кнопку входа через провайдер

2. Перенаправление: система перенаправляет пользователя на страницу авторизации провайдера с параметрами:

   • client_id — идентификатор клиента

   • redirect_uri — URI для возврата после авторизации

   • response_type=code — тип ответа (authorization code)

   • scope — запрашиваемые разрешения

   • state — случайная строка для защиты от CSRF

3. Авторизация у провайдера: пользователь вводит учетные данные

4. Callback: провайдер перенаправляет пользователя обратно в Бипиум с кодом авторизации

5. Обмен кода на токен: Бипиум обменивает код на access token

6. Получение информации о пользователе: Бипиум запрашивает информацию о пользователе по access token

7. Создание/вход аккаунта: система создает аккаунт или входит в существующий по email

Безопасность

При настройке OAuth провайдеров важно:

• Хранить Client Secret в безопасности: не передавать его в открытом виде

• Использовать HTTPS: все запросы должны идти по защищенному соединению

• Правильно настроить Redirect URI: указать точный URL без подстановочных символов

• Использовать state параметр: система автоматически использует state для защиты от CSRF атак

• Ограничивать scope: запрашивать только необходимые разрешения

Связи с другими каталогами

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

• Компании — провайдеры могут быть привязаны к конкретным компаниям в мультидоменной конфигурации. Подробнее см. в документации по каталогу Компании

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

Часто задаваемые вопросы

Почему провайдер не отображается на странице входа?

Основные причины:

1. Переключатель Активна выключен

2. Неверно указаны ClientID или Client Secret

3. Неправильно настроен Redirect URI у провайдера

4. Ограничения по компаниям — если указаны компании, убедитесь, что вы входите в правильную компанию

Важно: Подробные решения типичных проблем при настройке SSO см. в разделе "Устранение неполадок" документации SSO (Single Sign-On).

Что делать, если вход через провайдер не работает?

Если вход через провайдер не работает, проверьте:

1. Логи сервера на наличие ошибок, связанных с OAuth

2. Настройки Redirect URI у провайдера

3. Корректность ClientID и Client Secret в каталоге

4. Сетевые настройки — доступность endpoints провайдера с сервера

Подробнее: см. раздел "Устранение неполадок" в SSO (Single Sign-On).

Можно ли использовать один провайдер для нескольких компаний?

Да, один провайдер может использоваться для нескольких компаний:

• Если поле Компании пустое, провайдер доступен для всех компаний

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

• Можно создать несколько записей одного типа провайдера с разными настройками для разных компаний

Как настроить несколько провайдеров одного типа?

Можно создать несколько записей одного типа провайдера (например, несколько Google провайдеров) с разными настройками:

1. Создайте несколько записей с типом "Google"

2. Укажите разные ClientID и Client Secret для каждой записи

3. Настройте разные компании для каждой записи (если нужно)

4. Все активные провайдеры будут отображаться на странице входа

Что такое Scope и зачем он нужен?

Scope — это набор разрешений, которые запрашиваются у провайдера для получения информации о пользователе:

• openid — для провайдеров, поддерживающих OpenID Connect

• profile — для получения профиля пользователя

• email — для получения email пользователя

Для предустановленных провайдеров (Google, Yandex, Mail.ru, VK) scope настраивается автоматически. Для OAuth2 и Keycloak может потребоваться указать scope вручную.

Можно ли изменить Redirect URI?

Redirect URI фиксирован и имеет формат:

https://ваш-домен.com/auth/callback

Этот URI должен быть указан в настройках приложения у провайдера. Изменить его в Бипиуме нельзя, так как он является частью системы аутентификации.

Поддержка

Если у вас возникли вопросы или проблемы при работе с каталогом OAuth провайдеры, обратитесь к технической поддержке Бипиум [email protected], предоставив:

• Версию Бипиум

• Описание проблемы или вопроса

• Тип провайдера (Google, Yandex, Keycloak и т.д.)

• Скриншоты настроек (если применимо)

• Логи сервера с ошибками (если применимо)

Дополнительные ресурсы

• SSO (Single Sign-On) — подробная документация по настройке всех типов провайдеров и устранению неполадок

• Документация по каталогу Компании

• Документация по каталогу Аккаунты