Подключите Element Web к Keycloak через Synapse OIDC.
Настройте клиент Keycloak OIDC и провайдер Synapse, чтобы пользователи Element Web могли входить в систему через ваш сервер идентификации, не раскрывая секретные данные клиентов.
Чтобы добавить авторизацию через 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) и не определитесь с способом создания учетных записей.
В домене 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; это необязательно и не связано с базовым входом в систему.
Отредактируйте активный файл 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]. Следуйте инструкциям вашего разработчика пакета для других методов установки.
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 и конфигурации сервера; лучше протестировать поведение, а не полагаться на конкретную метку.
Откройте 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. После того, как тестовая учетная запись успешно войдет в систему и у вас будет маршрут восстановления, задокументируйте окончательный обратный вызов, эмитента и сопоставление утверждений для администраторов.
Настройте клиент Keycloak OIDC и провайдер Synapse, чтобы пользователи Element Web могли входить в систему через ваш сервер идентификации, не раскрывая секретные данные клиентов.
Сохраните ключ восстановления, проверьте свои сеансы Element и убедитесь, что ключи зашифрованных сообщений можно восстановить, не путая резервную копию с паролем вашей учетной записи.
Диагностика сбоев, связанных с нехваткой памяти в Synapse во время синхронизации, безопасная настройка кэширования, выявление задержек запросов и проверка стабильного использования памяти.
Выявите причину сбоев сертификатов федерации Matrix и определите правильный сервер, восстановите цепочку TLS или доверие к центру сертификации, а также проверьте правильность решения без отключения проверок безопасности.
Маршрутизация клиентов Matrix и федерация через Cloudflare по протоколу HTTPS 443, сохранение обнаружения Synapse и предотвращение кэширования API-трафика или нарушения загрузки медиафайлов.
Создайте резервную копию Synapse с помощью pg_dump, защитите ключ подписи и носители, а затем восстановите данные в чистую базу данных PostgreSQL, не используя повторно устаревшие одноразовые ключи.
Настройте Mjölnir, используя выделенный аккаунт Matrix, зашифрованную комнату управления, Docker Compose, список политик и проверки разрешений.
Откажитесь от устаревшего прокси и настройте встроенную в Synapse функцию Sliding Sync. Проверьте обнаружение клиентов, затем измерьте скорость загрузки списка комнат и поведение при переподключении на совместимом телефоне.
Разверните Element Web как статический сайт, укажите в качестве сервера ваш домашний сервер Matrix, добавьте HTTPS и настройте Nginx для обслуживания обновлений без устаревших файлов.
Настройте Conduit на 64-битном Raspberry Pi 4 с сохранением данных, федерацией HTTPS, защищенной регистрацией и проверкой работоспособности домашнего сервера.