Подключите Element Web к Keycloak через Synapse OIDC.

Чтобы добавить авторизацию через Keycloak в Element Web, настройте Keycloak в качестве поставщика OpenID Connect (OIDC) в Synapse, а затем убедитесь, что Element Web использует этот домашний сервер Synapse. Synapse обрабатывает перенаправление аутентификации и обратный вызов; Element Web не нуждается в секретном ключе клиента Keycloak.

Пример сценария (гипотетический): небольшая организация использует Element Web по адресу chat.example.org, Synapse по адресу matrix.example.org, и Keycloak по адресу login.example.org. Та же последовательность применяется и к другим именам хостов, но каждый URL-адрес должен соответствовать вашей фактической общедоступной конфигурации. Этот пример является иллюстративным, а не описанием работающей системы.

Что вам понадобится перед изменением настроек

Используйте общедоступные HTTPS-адреса для Keycloak и Synapse. Документация Synapse по OIDC требует наличия защищенного источника для поставщика идентификации, а его функция обратного вызова должна быть доступна через общедоступный URL-адрес Synapse. Подтвердите имя области в Keycloak, в Synapse public_baseurlи URL-адрес домашнего сервера, обслуживаемого Element Web. Если перед любой из этих служб находится обратный прокси-сервер, он должен передавать запросы на правильный бэкэнд и сохранять внешний HTTPS-хост и схему.

В текущей конфигурации Synapse используется oidc_providersсписок. Более старая oidc_configформа с одним поставщиком устарела. Во время тестирования сохраните рабочий логин администратора и копию текущей конфигурации. Не отключайте вход по паролю или регистрацию, пока не проверите процесс единого входа (SSO) и не определитесь с способом создания учетных записей.

1. Зарегистрируйте Synapse в качестве клиента в Keycloak.

В домене Keycloak, где находятся пользователи вашей организации, создайте клиент OpenID Connect для Synapse. В официальном примере Keycloak для Synapse используется конфиденциальный клиент с идентификатором клиента synapse. Установите допустимый URI перенаправления на этот же самый обратный вызов, заменив имя хоста Synapse:

https://matrix.example.org/_synapse/client/oidc/callback

В гипотетической конфигурации установите тип доступа клиента на «конфиденциальный» и включите клиента. На вкладке «Учетные данные» скопируйте сгенерированный секрет клиента в вашу систему управления секретами; не размещайте его в общедоступной папке Element Web config.jsonи не публикуйте в репозитории.

URI перенаправления часто является причиной сбоев. Он должен использовать общедоступный URL-адрес Synapse, точный /_synapse/client/oidc/callbackпуть, а также ту же схему и имя хоста, которые Synapse видит в браузере. Избегайте использования широкого символа подстановки в качестве обратного вызова, если подойдет точный URI. Если вы позже включите выход из системы через обратный канал, добавьте также документированную конечную точку обратного канала Synapse в Keycloak; это необязательно и не связано с базовым входом в систему.

2. Добавьте провайдер Keycloak в Synapse.

Отредактируйте активный файл homeserver.yaml. Замените указанные ниже область действия (realm) и секрет (secret) своими значениями и подтвердите URL-адрес эмитента из документа обнаружения OpenID для данной области действия. Стандартный эмитент области действия Keycloak имеет следующую структуру:

https://login.example.org/realms/your-realm

Для развертывания с использованием стандартной конечной точки обнаружения и утверждений, показанных в примере Keycloak в Synapse, запись поставщика выглядит следующим образом:

oidc_providers:
  - idp_id: keycloak
    idp_name: "Company Login"
    issuer: "https://login.example.org/realms/your-realm"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_KEYCLOAK_SECRET"
    scopes: ["openid", "profile"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

Эмитент должен совпадать с эмитентом области Keycloak, а не только с корневым сервером Keycloak. Discovery позволяет Synapse получать конечные точки авторизации, токена и информации о пользователе от этого эмитента. В сопоставлении используется Keycloak preferred_usernameдля формирования локальной части Matrix и nameв качестве отображаемого имени; убедитесь, что эти утверждения присутствуют и стабильны для ваших пользователей. Локальная часть Matrix — это идентификатор учетной записи, поэтому изменение сопоставления позже может запутать сопоставление учетных записей или привести к появлению другого идентификатора Matrix.

Сохраните существующий oidc_providersсписок, если настроены другие поставщики идентификации; добавьте эту запись вместо замены несвязанных поставщиков. Защитите секрет клиента как секрет и установите права доступа к файлу в соответствии с вашей конфигурацией развертывания. Проверьте отступы YAML, затем перезапустите Synapse, используя процедуру службы или контейнера для вашей установки. Пакетные установки могут уже включать зависимости OIDC; для установки в виртуальном окружении Synapse описывает установку matrix-synapse[oidc]. Следуйте инструкциям вашего разработчика пакета для других методов установки.

3. Веб-элемент Point Element на том же домашнем сервере.

Element Web config.jsonдолжен идентифицировать сервер Synapse как свой домашний сервер, например, с помощью `<homeserver>` default_server_config.mHomeserver.base_url. Используйте фактический URL домашнего сервера, а не URL эмитента Keycloak. Element Web — это статический клиент: после изменения URL домашнего сервера переразверните или перезагрузите его конфигурацию, используя свой хостинг. Не помещайте секретный ключ клиента Keycloak в этот файл, поскольку браузеры могут его прочитать.

В качестве гипотетического примера, Element Web размещен по адресу https://chat.example.orgи подключается к https://matrix.example.org. Когда пользователь выбирает опцию SSO на экране входа в Element, браузер должен пройти через процесс авторизации Synapse в область Keycloak и вернуться к обратному вызову Synapse. Точная формулировка кнопок и расположение элементов на экране входа могут различаться в зависимости от версии Element Web и конфигурации сервера; лучше протестировать поведение, а не полагаться на конкретную метку.

4. Перед внедрением единого входа (SSO) протестируйте систему на одной учетной записи.

Откройте Element Web в приватном окне браузера и выберите опцию входа через SSO. Войдите в систему под тестовым пользователем Keycloak, подтвердите запрошенный доступ, если потребуется, и убедитесь, что браузер возвращается на нужный домашний сервер и открывает ожидаемую учетную запись Matrix. Проверьте, что полученный идентификатор Matrix содержит нужную локальную часть. Просмотрите журналы Synapse и Keycloak, если браузер выдает ошибку.

Если перенаправление не удается, сравните URL-адрес обратного вызова в Keycloak символ за символом с публичным URL-адресом обратного вызова Synapse. «Несоответствие издателя» указывает на неправильный издатель области или имя хоста обратного прокси. Отсутствие имени пользователя или ошибка сопоставления означает, что настроенное утверждение отсутствует или не подходит; проверьте утверждения тестового пользователя и намеренно скорректируйте сопоставление. Если браузер обращается к Keycloak, но не возвращает ответ, проверьте TLS-сертификаты и маршрутизацию прокси для обратного вызова Synapse.

Дополнительный выход из системы: Synapse поддерживает выход из системы через обратный канал OIDC. Чтобы использовать его, установите соответствующий параметр backchannel_logout_enabled: trueв настройках этого провайдера и укажите URL-адрес выхода из системы через обратный канал Keycloak как https://matrix.example.org/_synapse/client/oidc/backchannel_logout. Synapse также описывает включение параметра session-required в Keycloak. Это обрабатывает уведомления о выходе из системы, инициированные провайдером; это не обязательно для корректной работы первоначального входа через SSO.

Перед развертыванием: решите, следует ли SSO создавать новых пользователей Matrix или аутентифицировать только учетные записи, которые вы создаете отдельно, затем ознакомьтесь с параметрами OIDC Synapse для установленной вами версии. Метки конфигурации и пользовательский интерфейс администрирования Keycloak могут меняться между выпусками. Описанные здесь шаги соответствуют документации Synapse по OIDC, доступной с 10 октября 2026 года, и предполагают стандартную область Keycloak и развертывание Synapse с использованием документированного формата поставщика. Перед применением настроек, специфичных для версии, ознакомьтесь с руководством Synapse OpenID Connect и Keycloak , справочником по конфигурации Synapse и официальной документацией Keycloak. После того, как тестовая учетная запись успешно войдет в систему и у вас будет маршрут восстановления, задокументируйте окончательный обратный вызов, эмитента и сопоставление утверждений для администраторов.

Оставить комментарий

Подключите Element Web к Keycloak через Synapse OIDC.

Настройте клиент Keycloak OIDC и провайдер Synapse, чтобы пользователи Element Web могли входить в систему через ваш сервер идентификации, не раскрывая секретные данные клиентов.

Настройте безопасное резервное копирование ключей элементов и перекрестную подпись.

Настройте безопасное резервное копирование ключей элементов и перекрестную подпись.

Сохраните ключ восстановления, проверьте свои сеансы Element и убедитесь, что ключи зашифрованных сообщений можно восстановить, не путая резервную копию с паролем вашей учетной записи.

Остановите сбои памяти Matrix Synapse во время синхронизации клиента.

Диагностика сбоев, связанных с нехваткой памяти в Synapse во время синхронизации, безопасная настройка кэширования, выявление задержек запросов и проверка стабильного использования памяти.

Устранение ошибок TLS-сертификата Synapse Federation

Выявите причину сбоев сертификатов федерации Matrix и определите правильный сервер, восстановите цепочку TLS или доверие к центру сертификации, а также проверьте правильность решения без отключения проверок безопасности.

Безопасная установка сервера Synapse Matrix за Cloudflare.

Безопасная установка сервера Synapse Matrix за Cloudflare.

Маршрутизация клиентов Matrix и федерация через Cloudflare по протоколу HTTPS 443, сохранение обнаружения Synapse и предотвращение кэширования API-трафика или нарушения загрузки медиафайлов.

Безопасное восстановление Matrix Synapse с помощью дампа PostgreSQL

Создайте резервную копию Synapse с помощью pg_dump, защитите ключ подписи и носители, а затем восстановите данные в чистую базу данных PostgreSQL, не используя повторно устаревшие одноразовые ключи.

Запустите Mjölnir в качестве бота для модерации комнат Matrix с помощью Docker.

Запустите Mjölnir в качестве бота для модерации комнат Matrix с помощью Docker.

Настройте Mjölnir, используя выделенный аккаунт Matrix, зашифрованную комнату управления, Docker Compose, список политик и проверки разрешений.

Включите встроенную синхронизацию Matrix Sliding для более быстрой загрузки на мобильных устройствах.

Включите встроенную синхронизацию Matrix Sliding для более быстрой загрузки на мобильных устройствах.

Откажитесь от устаревшего прокси и настройте встроенную в Synapse функцию Sliding Sync. Проверьте обнаружение клиентов, затем измерьте скорость загрузки списка комнат и поведение при переподключении на совместимом телефоне.

Разместите Element Web на Nginx с пользовательским Homeserver.

Разверните Element Web как статический сайт, укажите в качестве сервера ваш домашний сервер Matrix, добавьте HTTPS и настройте Nginx для обслуживания обновлений без устаревших файлов.

Запустите облегченный домашний сервер Matrix на Raspberry Pi 4.

Настройте Conduit на 64-битном Raspberry Pi 4 с сохранением данных, федерацией HTTPS, защищенной регистрацией и проверкой работоспособности домашнего сервера.