warning

Этот учебник является вкладом сообщества и не поддерживается командой Open WebUI. Он служит только демонстрацией того, как настроить Open WebUI для ваших конкретных целей. Хотите внести вклад? Ознакомьтесь с учебником по внесению вклада.

🔗 Интеграция Okta OIDC SSO

Обзор

На этой странице документации описаны шаги по интеграции Okta OIDC Single Sign-On (SSO) с Open WebUI. Также рассматриваются необязательные функции управления группами пользователей Open WebUI на основе членства в группах Okta, включая создание групп по мере необходимости (JIT). Следуя этим шагам, вы сможете разрешить пользователям вход в Open WebUI с использованием их учетных данных Okta. Если вы решите включить синхронизацию групп (ENABLE_OAUTH_GROUP_MANAGEMENT), пользователи будут автоматически назначены в соответствующие группы в Open WebUI на основе своих групп в Okta при входе. Если вы также включите создание групп по мере необходимости (ENABLE_OAUTH_GROUP_CREATION), группы, присутствующие в заявлениях Okta, но отсутствующие в Open WebUI, будут создаваться автоматически во время входа.

Предварительные условия

• Новый или существующий экземпляр Open WebUI.
• Учетная запись Okta с административными привилегиями для создания и настройки приложений.
• Базовое понимание OIDC, настройки приложений Okta и переменных окружения Open WebUI.

Настройка Okta

Сначала необходимо настроить OIDC-приложение в вашей организации Okta и создать заявление о группах для передачи информации о группах в Open WebUI.

1. Создание/Настройка OIDC приложения в Okta

1. Войдите в консоль администратора Okta.
2. Перейдите в Приложения > Приложения.
3. Либо создайте новое приложение OIDC - OpenID Connect (выберите тип Веб-приложение), либо выберите существующее, которое вы хотите использовать для Open WebUI.
4. В процессе настройки или на вкладке Общие настройки приложения укажите URI перенаправления для входа. Добавьте URI вашего экземпляра Open WebUI с окончанием /oauth/oidc/callback. Пример: https://your-open-webui.com/oauth/oidc/callback.
5. Запишите ID клиента и секрет клиента, указанные на вкладке Общие приложения. Вам понадобятся они для настройки Open WebUI.
6. Убедитесь, что правильные пользователи или группы назначены для этого приложения на вкладке Назначения.

2. Добавление заявления о группах в ID-токен

(Необязательно) Чтобы включить автоматическое управление группами в Open WebUI на основе Okta, необходимо настроить Okta для передачи членства пользователя в группах через ID-токен. Если вам нужен только вход через SSO и вы предпочитаете управлять группами вручную внутри Open WebUI, этот раздел можно пропустить.

1. В консоли администратора перейдите в Приложения > Приложения и выберите ваше приложение клиента OIDC.
2. Перейдите на вкладку Вход и нажмите Редактировать в разделе ID-токен OpenID Connect.
3. В разделе Тип заявления о группах выберите Фильтр.
4. В разделе Фильтр заявлений о группах:
   • Введите groups в качестве имени заявления (или используйте значение по умолчанию, если оно доступно).
   • Выберите Соответствует регулярному выражению из выпадающего списка.
   • Введите .* в поле регулярного выражения. Это включит все группы, членом которых является пользователь. Вы можете использовать более конкретное регулярное выражение, если необходимо.
5. Нажмите Сохранить.
6. Нажмите на ссылку Вернуться к приложениям.
7. Во всплывающем меню кнопки Еще вашего приложения нажмите Обновить данные приложения.

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

Настройка Open WebUI

Чтобы включить Okta OIDC SSO в Open WebUI, необходимо установить следующие основные переменные окружения. Дополнительные переменные потребуются, если вы хотите включить необязательную функцию управления группами.

# --- Основные настройки OIDC ---
# Включите регистрацию через OAuth, если вы хотите, чтобы пользователи могли создавать учетные записи через Okta
# ENABLE_OAUTH_SIGNUP="true"

# ID клиента вашего приложения Okta
OAUTH_CLIENT_ID="YOUR_OKTA_CLIENT_ID"

# Секрет клиента вашего приложения Okta
OAUTH_CLIENT_SECRET="YOUR_OKTA_CLIENT_SECRET"

# URL для обнаружения OIDC вашей организации Okta
# Формат: https://<your-okta-domain>/.well-known/openid-configuration
# Или для конкретного сервера авторизации: https://<your-okta-domain>/oauth2/<auth-server-id>/.well-known/openid-configuration
OPENID_PROVIDER_URL="YOUR_OKTA_OIDC_DISCOVERY_URL"

# Имя, отображаемое на кнопке входа (например, "Вход через Okta")
OAUTH_PROVIDER_NAME="Okta"

# Запрашиваемые области (по умолчанию обычно достаточно)
# OAUTH_SCOPES="openid email profile groups" # Убедитесь, что 'groups' включен, если не по умолчанию

# --- Управление группами через OAuth (необязательно) ---
# Установите в "true" только если вы настроили заявление о группах в Okta (Шаг 2)
# и хотите, чтобы группы Open WebUI управлялись на основе групп Okta при входе в систему.
# Это синхронизирует существующие группы. Пользователи будут добавлены/удалены из групп Open WebUI
# чтобы соответствовать их утверждениям группы Okta.
# ENABLE_OAUTH_GROUP_MANAGEMENT="true"

# Требуется только если ENABLE_OAUTH_GROUP_MANAGEMENT равно true.
# Название утверждения в ID-токене, содержащее информацию о группах (должно совпадать с настройками Okta)
# OAUTH_GROUP_CLAIM="groups"

# Опционально: Включение создания групп в режиме Just-in-Time (JIT), если они существуют в утверждениях Okta, но отсутствуют в Open WebUI.
# Требуется ENABLE_OAUTH_GROUP_MANAGEMENT="true".
# Если установлено в false (по умолчанию), будут синхронизироваться только существующие группы.
# ENABLE_OAUTH_GROUP_CREATION="false"

Замените YOUR_OKTA_CLIENT_ID, YOUR_OKTA_CLIENT_SECRET и YOUR_OKTA_OIDC_DISCOVERY_URL фактическими значениями из конфигурации вашего приложения Okta.

Чтобы включить синхронизацию групп на основе утверждений Okta, установите ENABLE_OAUTH_GROUP_MANAGEMENT="true" и убедитесь, что OAUTH_GROUP_CLAIM совпадает с названием утверждения, настроенного в Okta (по умолчанию это groups).

Чтобы также включить автоматическое создание групп в режиме Just-in-Time (JIT), которые существуют в Okta, но еще не существуют в Open WebUI, установите ENABLE_OAUTH_GROUP_CREATION="true". Можно оставить это значение false, если вы хотите управлять только участием в группах, которые уже существуют в Open WebUI.

:::предупреждение Управление участием в группах Когда ENABLE_OAUTH_GROUP_MANAGEMENT установлено в true, участие пользователя в группах Open WebUI будет строго синхронизировано с группами, полученными в их утверждениях Okta при каждом входе в систему. Это означает:

• Пользователи будут добавлены в группы Open WebUI, которые соответствуют их утверждениям Okta.
• Пользователи будут удалены из любых групп Open WebUI (включая те, которые были созданы или назначены вручную в Open WebUI), если эти группы не присутствуют в их утверждениях Okta в текущей сессии входа.

Убедитесь, что все необходимые группы правильно настроены и назначены в Okta и включены в утверждение группы. :::

:::информация Сохранение сессий в многозвенных установках

При развертывании Open WebUI на нескольких узлах (например, в кластере Kubernetes или за балансировщиком нагрузки) крайне важно обеспечить сохранение сессий для бесшовного взаимодействия с пользователем, особенно при использовании SSO. Установите переменную окружения WEBUI_SECRET_KEY в одно и то же защищенное, уникальное значение на всех экземплярах Open WebUI. :::

# Пример: Создание сильного секретного ключа (например, с использованием openssl rand -hex 32)
WEBUI_SECRET_KEY="YOUR_UNIQUE_AND_SECURE_SECRET_KEY"

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

:::подсказка Отключение стандартной формы входа

Если вы хотите разрешить вход только через Okta (а также потенциально других настроенных провайдеров OAuth), вы можете отключить стандартную форму входа по адресу электронной почте/паролю, установив следующую переменную окружения: :::

ENABLE_LOGIN_FORM="false"

:::опасность Важно: предварительные условия Установка ENABLE_LOGIN_FORM="false" требует, чтобы также была установлена ENABLE_OAUTH_SIGNUP="true". Если вы отключите форму входа, не включив регистрацию через OAuth, пользователи (включая администраторов) не смогут войти в систему. Убедитесь, что по крайней мере один поставщик OAuth настроен и что ENABLE_OAUTH_SIGNUP включен, прежде чем отключать стандартную форму входа. :::

Перезапустите ваш экземпляр Open WebUI после установки этих переменных окружения.

Проверка

1. Перейдите на страницу входа вашего Open WebUI. Вы должны видеть кнопку с надписью «Войти через Okta» (или то, что вы установили для OAUTH_PROVIDER_NAME).
2. Нажмите кнопку и пройдите процесс аутентификации через Okta.
3. После успешной аутентификации вы должны быть перенаправлены обратно в Open WebUI и войти в систему.
4. Если ENABLE_OAUTH_GROUP_MANAGEMENT равно true, войдите как неадминистраторский пользователь. Их группы в Open WebUI теперь должны строго отражать их текущие членства в группах в Okta (любые участия в группах, которые не входят в утверждение Okta, будут удалены). Если ENABLE_OAUTH_GROUP_CREATION также равно true, любые группы, присутствующие в утверждениях Okta пользователя, которые ранее не существовали в Open WebUI, теперь должны быть автоматически созданы. Обратите внимание, что группы администраторов не обновляются автоматически через SSO.
5. Проверьте журналы сервера Open WebUI на наличие ошибок, связанных с OIDC или группами, если вы столкнетесь с проблемами.

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

• 400 Bad Request/Redirect URI Mismatch: Убедитесь, что URI перенаправления входа в вашем приложении Okta точно соответствует <your-open-webui-url>/oauth/oidc/callback.
• Группы не синхронизируются: Убедитесь, что переменная окружения OAUTH_GROUP_CLAIM совпадает с названием утверждения, настроенного в настройках ID-токена Okta. Убедитесь, что пользователь вышел и заново вошел в систему после изменений в группах — для обновления OIDC требуется процесс входа. Помните, что группы администраторов не синхронизируются.
• Ошибки конфигурации: Просмотрите журналы сервера Open WebUI для получения подробных сообщений об ошибках, связанных с конфигурацией OIDC.
• Обратитесь к официальной документации Open WebUI SSO.
• Ознакомьтесь с документацией разработчика Okta.