8-800-505-24-05

SSO (Single Sign-On)

Введение

Single Sign-On (SSO) позволяет пользователям входить в Бипиум, используя учетные данные из внешней системы аутентификации (например, Keycloak, Active Directory через Keycloak и т.д.). Это упрощает управление доступом и повышает безопасность.

Преимущества SSO

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

  • Централизованное управление: администраторы управляют доступом из одного места

  • Повышенная безопасность: единые политики безопасности и аудит

  • Удобство: пользователям не нужно запоминать отдельные пароли

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

Бипиум поддерживает следующие SSO провайдеры через OAuth 2.0 / OpenID Connect:

  • Keycloak — рекомендуемый провайдер для корпоративных решений

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

  • Google — для интеграции с Google Workspace

  • Yandex — для интеграции с Yandex ID

  • Mail.ru — для интеграции с Mail.ru ID

  • VK — для интеграции с VK ID

Примечание: В данной статье основное внимание уделено настройке Keycloak, так как это наиболее распространенный выбор для серверных версий Бипиум.

Настройка социальных сетей (Google, Yandex, Mail.ru, VK)

Настройка провайдеров социальных сетей (Google, Yandex, Mail.ru, VK) выполняется по единой схеме, так как все они используют стандартный протокол OAuth 2.0. Основные шаги одинаковы для всех провайдеров.

Общая схема настройки

Шаг 1: Создание приложения у провайдера

  1. Перейдите на страницу разработчика выбранного провайдера:

  2. Создайте новое OAuth приложение

  3. Настройте Redirect URI (URI перенаправления):

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

  4. Сохраните Client ID и Client Secret — они понадобятся при настройке в Бипиуме

Шаг 2: Настройка провайдера в Бипиуме

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

  2. Перейдите в раздел Системные каталоги → OAuth провайдеры

  3. Нажмите Создать запись

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

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

    • Провайдер: выберите нужный провайдер (Google, Yandex, Mail.ru или VK)

    • ClientID: вставьте Client ID, полученный у провайдера

    • Client secret: вставьте Client Secret, полученный у провайдера

    • Порядковый номер в списке: укажите число для сортировки кнопок (например, 1)

  5. (Опционально) Настройте кнопку входа:

    • Подпись: текст для кнопки (например, "Войти через Google")

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

  6. Нажмите Сохранить

Настройка SSO через Keycloak

Keycloak — это рекомендуемый провайдер SSO для корпоративных решений. Настройка включает два основных этапа:

  1. Настройка Keycloak на стороне сервера

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

Настройка Keycloak на стороне сервера

Шаг 1: Установка и настройка Keycloak

Если у вас еще не установлен Keycloak, выполните его установку согласно официальной документации.

Шаг 2: Создание Realm

  1. Войдите в административную консоль Keycloak (обычно http://your-keycloak-server:8080)

  2. Создайте новый Realm или используйте существующий (например, master)

  3. Запомните URL вашего Realm, он понадобится позже:

Шаг 3: Создание клиента (Client) в Keycloak

  1. В разделе Clients нажмите Create client

  2. Заполните форму:

    • Client type: OpenID Connect

    • Client ID: bpium (или любое другое уникальное имя)

    • Нажмите Next

  3. Настройте параметры клиента:

    • Client authentication: On (если требуется Client Secret)

    • Authorization: Off (обычно не требуется)

    • Authentication flow: оставьте значения по умолчанию

    • Нажмите Next

  4. Настройте Valid redirect URIs:

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

  5. Настройте Web origins (если требуется CORS):

  6. Нажмите Save

Шаг 4: Получение Client ID и Client Secret

  1. В настройках созданного клиента перейдите на вкладку Credentials

  2. Скопируйте значение Client ID

  3. Если включена Client authentication, скопируйте значение Client secret

    • Если секрет не отображается, нажмите Regenerate Secret и сохраните новое значение

Шаг 5: Настройка маппинга пользователей (опционально)

По умолчанию Keycloak использует следующие поля для идентификации пользователя:

  • Логин (email): поле preferred_username из ID токена

  • Имя пользователя: поле name из ID токена

Если в вашем Keycloak используются другие поля, запомните их названия — они понадобятся при настройке в Бипиуме.

Настройка SSO провайдера в Бипиуме

Шаг 1: Открытие каталога OAuth провайдеров

  1. Войдите в Бипиум с правами администратора. По умолчанию admin/admin

  2. Перейдите в раздел Системные каталоги → OAuth провайдеры

  3. Нажмите Создать запись

Шаг 2: Заполнение основных параметров

Заполните следующие обязательные поля:

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

  • Активна: включите переключатель (должен быть включен)

  • Провайдер: выберите Keycloak

  • ClientID: вставьте Client ID, скопированный из Keycloak

  • Client secret: вставьте Client Secret, скопированный из Keycloak

  • Порядковый номер в списке: укажите число для сортировки кнопок на странице входа (например, 1)

Компании (для мультидоменных установок)

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

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

Шаг 3: Настройка кнопки входа (опционально)

  • Подпись: текст, который будет отображаться на кнопке входа (например, "Войти через Keycloak")

  • Иконка: загрузите изображение для кнопки (рекомендуемый размер: 24x24 или 32x32 пикселя)

Если эти поля не заполнены, будут использованы значения по умолчанию.

Шаг 4: Дополнительные настройки

В разделе Дополнительные настройки заполните:

Другие параметры (JSON)

Это обязательное поле для Keycloak. Укажите JSON с параметром realmUrl:

Примеры:

  • Для HTTP: {"realmUrl": "http://192.168.1.100:8080/realms/master"}

  • Для HTTPS: {"realmUrl": "https://keycloak.company.com/realms/production"}

Важно:

  • URL должен быть доступен с сервера Бипиум

  • Убедитесь, что указан правильный Realm

  • Для продуктивной среду рекомендуется использовать HTTPS

Поле логина (опционально)

Если в Keycloak используется нестандартное поле для логина (email), укажите его здесь. По умолчанию используется preferred_username.

Примеры:

  • email — если логин хранится в поле email

  • sub — если используется ID пользователя

  • username — если используется поле username

Поле имени пользователя (опционально)

Если в Keycloak используется нестандартное поле для имени пользователя, укажите его здесь. По умолчанию используется name.

Примеры:

  • given_name — для имени

  • full_name — для полного имени

  • display_name — для отображаемого имени

Scope (опционально)

Укажите дополнительные scope, разделенные пробелами, если требуется дополнительная информация о пользователе.

Примеры:

  • openid profile email — стандартный набор для OpenID Connect

  • openid email — минимальный набор (openid добавляется автоматически)

Примечание: Scope openid добавляется автоматически для Keycloak, указывать его не обязательно.

Шаг 5: Сохранение настроек

  1. Проверьте все заполненные поля

  2. Нажмите Сохранить

Пример полной конфигурации Keycloak

Ниже приведен пример заполнения всех полей для типичной настройки Keycloak:

В Keycloak:

  • Realm URL: https://keycloak.company.com/realms/production

  • Client ID: bpium-production

  • Client Secret: abc123def456ghi789...

  • Valid redirect URIs:

    • https://bpium.company.com/auth/callback

    • https://app.company.com/auth/callback

В Бипиум (каталог OAuth провайдеры):

Поле
Значение

Активна

Включено

Провайдер

Keycloak

ClientID

bpium-production

Client secret

abc123def456ghi789...

Порядковый номер

1

Компании

(оставить пустым для всех компаний)

Подпись

Войти через корпоративный аккаунт

Иконка

(загрузить логотип компании)

Другие параметры

{"realmUrl": "https://keycloak.company.com/realms/production"}

Поле логина

preferred_username (или оставить пустым)

Поле имени пользователя

name (или оставить пустым)

Scope

openid profile email (или оставить пустым)

Проверка работы SSO

Шаг 1: Проверка на странице входа

  1. Выйдите из Бипиум (если вы вошли)

  2. Откройте страницу входа

  3. Убедитесь, что появилась кнопка с вашим SSO провайдером (например, "Войти через Keycloak")

Шаг 2: Тестовая авторизация

  1. Нажмите на кнопку SSO провайдера

  2. Должно произойти перенаправление на страницу входа провайдера (Keycloak, Google и т.д.)

  3. Введите учетные данные пользователя

  4. После успешной авторизации должно произойти перенаправление обратно в Бипиум

  5. Пользователь должен быть автоматически авторизован в Бипиум

Шаг 3: Проверка создания учетной записи

  • Если пользователь с таким email уже существует в Бипиум, он будет авторизован

  • Если пользователя нет, автоматически будет создан новый аккаунт в Бипиум (независимо от настроек регистрации)

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

  • Если у пользователя есть активные приглашения (invites) с привязкой к компании, они будут автоматически использованы

  • Если приглашений нет, администратор должен вручную привязать пользователя к компании после первого входа

  • Без привязки к компании пользователь увидит информационное сообщение "no-companies" и не сможет войти

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

Автоматическое создание аккаунтов при входе через SSO

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

  • Автоматическая привязка через приглашения:

    • Если для пользователя создано приглашение (invite) с привязкой к компании, при первом входе через SSO он автоматически будет привязан к этой компании

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

  • Ручная привязка администратором:

    • Если приглашения нет, администратор должен вручную привязать пользователя к компании после первого входа

    • Пользователь увидит ошибку "no-companies" до тех пор, пока не будет привязан к компании

  • Рекомендации:

    • Для корпоративных установок рекомендуется создавать приглашения заранее

    • Можно использовать API Бипиум для автоматического создания приглашений при добавлении пользователей в Keycloak

    • Настройте процесс синхронизации пользователей между провайдером и Бипиум

Настройка для нескольких компаний

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

  • Создайте отдельную запись провайдера для каждой компании

  • В поле Компании выберите соответствующую компанию

  • Настройте разные Client ID в провайдере для каждой компании (рекомендуется)

Настройка автоматического обновления токенов

Бипиум автоматически обновляет access token через refresh token, если провайдер поддерживает это. Убедитесь, что в провайдере:

  • Включена поддержка refresh tokens для клиента

  • Указаны правильные scope (обычно openid достаточно)

Интеграция с Active Directory через Keycloak

Если Keycloak подключен к Active Directory:

  • Настройте User Federation в Keycloak для подключения к AD

  • Настройте маппинг атрибутов, чтобы email пользователя из AD попадал в поле preferred_username или email в токене

  • В Бипиум укажите соответствующее поле в настройке Поле логина

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

Рекомендации по безопасности:

  • Используйте HTTPS для провайдера и Бипиум в production

  • Регулярно обновляйте Client Secret в провайдере и синхронизируйте изменения в Бипиум

  • Ограничьте Valid redirect URIs в провайдере только необходимыми доменами

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

  • Включите логирование в провайдере для аудита доступа

Устранение неполадок

Проблема: Кнопка SSO не отображается на странице входа

Возможные причины и решения:

  • Провайдер не активирован

    • Проверьте, что в настройках провайдера включен переключатель Активна

  • Провайдер недоступен для текущей компании

    • Проверьте настройки поля Компании в записи провайдера

    • Убедитесь, что текущая компания включена в список

  • Кэш браузера

    • Очистите кэш браузера или откройте страницу в режиме инкогнито

Проблема: Ошибка "Invalid redirect URI" в Keycloak

Причина: URL обратного вызова не зарегистрирован в Keycloak

Решение:

  1. Откройте настройки клиента в Keycloak

  2. Проверьте поле Valid redirect URIs

  3. Убедитесь, что там указан правильный URL:

  4. Если используется несколько доменов, добавьте все необходимые URL

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

Проблема: Ошибка "Provider is not found"

Причина: Провайдер не найден в базе данных

Решение:

  • Проверьте, что запись провайдера сохранена в каталоге OAuth провайдеры

  • Убедитесь, что провайдер активен

  • Попробуйте перезапустить сервер Бипиум

Проблема: Ошибка "Invalid client credentials"

Причина: Неверный Client ID или Client Secret

Решение:

  • Проверьте, что ClientID и Client secret в Бипиум совпадают с настройками в провайдере

  • Если Client Secret был изменен в провайдере, обновите его в Бипиум

  • Убедитесь, что в Keycloak включена Client authentication, если вы используете Client Secret

Проблема: Ошибка "realmUrl is required" (только для Keycloak)

Причина: Не указан или неверно указан параметр realmUrl в поле Другие параметры

Решение:

  • Проверьте формат JSON в поле Другие параметры

  • Убедитесь, что указан правильный URL Realm:

  • Проверьте доступность URL с сервера Бипиум (можно использовать curl или wget)

Проблема: Пользователь не может войти, хотя авторизация в провайдере прошла успешно

Возможные причины и решения:

  • Email пользователя не совпадает

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

    • Убедитесь, что в провайдере это поле содержит корректный email

    • Проверьте настройки Поле логина в Бипиум

  • Пользователь не привязан к компании (наиболее частая причина)

    • При первом входе через SSO аккаунт создается автоматически, но без привязки к компании

    • Пользователь увидит ошибку "no-companies" и не сможет войти

    • Решение: Администратор должен:

      1. Открыть каталог Аккаунты (Accounts)

      2. Найти пользователя по email

      3. Привязать его к нужной компании через поле Компании

    • Альтернатива: Создать приглашение (invite) для пользователя перед первым входом — тогда привязка произойдет автоматически

  • Проблемы с сессией

    • Очистите cookies браузера

    • Попробуйте войти в режиме инкогнито

Проблема: Ошибка сети при обращении к провайдеру

Причина: Сервер Бипиум не может подключиться к провайдеру

Решение:

  • Проверьте доступность провайдера с сервера Бипиум:

  • Проверьте настройки файрвола

  • Убедитесь, что URL в настройках корректен

Поддержка

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

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

  • Версию провайдера (Keycloak, Google и т.д.)

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

  • Логи сервера (если возможно)

  • Скриншоты ошибок

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

PreviousАктивацияNextБрендирование (Whitelabel)

Last updated