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 провайдеры

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

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

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

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

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

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

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

Как работают 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

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

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

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

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

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

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

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

После создания приложения у провайдера и получения 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. Сохраните запись

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

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

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

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

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

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

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

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

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

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

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

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

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

Можно создать несколько записей одного типа провайдера (например, несколько 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 провайдеры, обратитесь к технической поддержке Бипиум support@bpium.ru, предоставив:

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

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

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

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

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

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

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

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

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