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:

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

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

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

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

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

  6. 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. Нажмите Сохранить

Настройка 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. Нажмите Сохранить

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

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

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

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

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

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

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

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

  3. Введите учетные данные пользователя, существующего в Keycloak

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  3. Кэш браузера

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

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

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

Решение:

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

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

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

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

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

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

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

Решение:

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

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

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

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

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

Решение:

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

  2. Если Client Secret был изменен в Keycloak, обновите его в Бипиум

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

Проблема: Ошибка "realmUrl is required"

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

Решение:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  3. Проблемы с сессией

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

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

Проблема: Ошибка сети при обращении к Keycloak

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

Решение:

  1. Проверьте доступность Keycloak с сервера Бипиум:

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

  3. Убедитесь, что URL в параметре realmUrl корректен

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

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

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

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

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

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

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

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

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

  3. Рекомендации:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Используйте HTTPS для Keycloak и Бипиум в production

  2. Регулярно обновляйте Client Secret в Keycloak и синхронизируйте изменения в Бипиум

  3. Ограничьте Valid redirect URIs в Keycloak только необходимыми доменами

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

  5. Включите логирование в 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, обратитесь к технической поддержке Бипиум [email protected], предоставив:

  1. Версию Бипиум

  2. Версию Keycloak (или другого провайдера)

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

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

  5. Скриншоты ошибок

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

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

Last updated