Как настроить единый вход (SSO) с помощью Keycloak в Element Web

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

В этом руководстве используется встроенный в Synapse OIDC-провайдер, что является распространенным вариантом развертывания. Если ваш домашний сервер делегирует аутентификацию службе аутентификации Matrix Authentication Service (MAS), используйте вместо этого описанную ниже конфигурацию обратного вызова и провайдера MAS. Два URL-адреса обратного вызова различаются. Инструкции были проверены на соответствие документации по веб-конфигурации Element, руководству по OIDC для Synapse версии 1.144, текущему руководству по SSO от MAS и руководству администратора Keycloak 26.8.0 6 октября 2026 года; пакеты развертывания и метки пользовательского интерфейса могут различаться в зависимости от версии.

Во-первых, определите, какой путь аутентификации вы используете.

Перед созданием клиента ознакомьтесь с документацией по настройке и развертыванию Synapse. Функция обратного вызова должна принадлежать компоненту, взаимодействующему с Keycloak; не регистрируйте URL-адрес веб-сайта Element в качестве функции обратного вызова.

Что вам нужно

• Публичный HTTPS-адрес для Synapse, например https://matrix.example.com, , и доступный эмитент домена Keycloak, например https://sso.example.com/realms/company, .
• Административный доступ к домену Keycloak, а также к конфигурации и сервису Synapse.
• Резервная копия текущей конфигурации и возможность использования журналов Synapse или консоли сервера в случае сбоя входа в систему.
• Решение о предоставлении учетных записей: какие пользователи Keycloak могут входить в систему, какой параметр их идентифицирует и нужно ли сохранять существующие учетные записи Matrix.

Настройка Keycloak для Synapse OIDC

1. Создайте конфиденциальный OIDC-клиент.

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

Установите допустимый URI перенаправления на точный адрес обратного вызова Synapse:

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

Замените пример имени хоста на фактически настроенный для Synapse публичный базовый URL-адрес. Не используйте широкий подстановочный знак, как *в производственной среде. Keycloak проверяет URI перенаправления, поэтому несоответствие хоста, схемы, пути или завершающей косой черты может привести к ошибке «URI перенаправления не разрешен».

Сохраните клиент, скопируйте сгенерированный секрет и сохраните его как секрет на стороне сервера. Не допускайте его попадания в публичный репозиторий Element Web config.json, систему контроля версий, скриншоты и клиентский JavaScript. В консоли администратора Keycloak аутентификация клиента или учетные данные могут отличаться в разных версиях; убедитесь, что полученный клиент является конфиденциальным и может использовать стандартный поток авторизации.

2. Подтвердите эмитента и требования.

Эмитент определяет область действия, а не корневой каталог сервера Keycloak. В этом примере используйте https://sso.example.com/realms/company. Убедитесь, что конфигурация OpenID области действия доступна по адресу <issuer>/.well-known/openid-configurationи что заявленный эмитент точно соответствует значению, которое вы передадите Synapse.

Synapse требуется стабильное утверждение идентификации для связи учетной записи Keycloak с пользователем Matrix. Его поставщик OIDC обычно идентифицирует внешнего субъекта, используя утверждение субъекта OIDC; в приведенном ниже сопоставлении имен пользователей preferred_usernameв качестве локальной части Matrix используется именно это утверждение. Убедитесь, что Keycloak действительно возвращает это утверждение и что имена пользователей уникальны и стабильны в соответствии с вашей политикой учетных записей. Если ваша организация разрешает изменение имен пользователей, выберите и протестируйте стратегию сопоставления перед запуском в производство; неожиданное изменение сопоставления может повлиять на то, к какой учетной записи Matrix будет обращаться пользователь.

Настройка Synapse

3. Добавьте поставщика OIDC.

Добавьте запись поставщика в основную конфигурацию Synapse, обычно это `<provider>` homeserver.yaml. Объедините её с существующим YAML-файлом вместо замены других настроек. Замените `emissioner` вашего домена и реальный секретный ключ клиента:

oidc_providers:
  - idp_id: keycloak
    idp_name: "Keycloak"
    issuer: "https://sso.example.com/realms/company"
    client_id: "synapse"
    client_secret: "REPLACE_WITH_THE_CLIENT_SECRET"
    scopes: ["openid", "profile", "email"]
    user_mapping_provider:
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"

Указанные области действия определяют, какую информацию о пользователях Keycloak может возвращать; они не гарантируют заполнения всех полей. Если вам не требуется импорт электронной почты или отображаемого имени, уменьшите области действия и сопоставление соответствующим образом. Файл конфигурации должен быть доступен для чтения только администратору службы и процессу Synapse в соответствии с вашей конфигурацией. Если вы управляете Synapse через контейнеры или диаграмму, поместите параметры поставщика в поддерживаемый источник конфигурации, а не редактируйте сгенерированный файл, который будет перезаписан.

4. При желании можно настроить выход из системы через обратный канал.

По умолчанию выход из одной службы не обязательно завершает сеанс браузера во всех остальных службах. Если вы хотите, чтобы уведомления о выходе из Keycloak завершали сеанс Synapse, включите эту функцию backchannel_logout_enabled: trueв настройках поставщика Keycloak в Synapse и установите URL-адрес выхода из Backchannel Keycloak следующим образом:

https://matrix.example.com/_synapse/client/oidc/backchannel_logout

Это необязательно и зависит от вашей политики выхода из системы и настроек клиента. Проверьте оба способа выхода из системы: выход из Synapse и выход из Keycloak. Не следует предполагать, что выход из Element сам по себе завершает сессию Keycloak.

5. Перезапустите и проверьте работу Synapse.

Проверьте YAML-файл с помощью проверок конфигурации вашего развертывания, затем перезапустите или перезагрузите Synapse, используя метод, поддерживаемый вашим пакетом или контейнером. Просмотрите журналы Synapse на наличие ошибок обнаружения OIDC, аутентификации клиента, обратного вызова или сопоставления утверждений. Сначала используйте тестовую учетную запись и убедитесь, что ее идентификатор матрицы и отображаемое имя соответствуют ожидаемым значениям.

Настройка веб-элемента

6. Сделайте SSO необязательным или обеспечьте автоматическое перенаправление.

Как только Synapse объявит о возможности входа через OIDC, Element Web сможет предложить вариант входа через SSO. Настройки Element sso_redirect_optionsуправляют работой браузера; они не настраивают Keycloak и не хранят секретный ключ клиента. Добавьте подобную настройку в настройки Element Web, config.jsonесли хотите, чтобы неаутентифицированные посетители, попадающие на страницу приветствия или входа, перенаправлялись на доступный поток SSO:

{
  "sso_redirect_options": {
    "immediate": false,
    "on_welcome_page": true,
    "on_login_page": true
  }
}

Для развертывания, действительно требующего входа только через SSO, настройте "immediate": trueзапуск SSO для всех неаутентифицированных пользователей. Это может затруднить доступ к паролю или другим вариантам авторизации, поэтому протестируйте доступ для восстановления и администрирования, прежде чем применять это правило. Если пользователям необходимо выбирать между SSO и другим методом, оставьте автоматическое перенаправление отключенным и проверьте, отображается ли вариант SSO в процессе входа в систему.

Если Synapse использует службу аутентификации Matrix

MAS — это отдельная служба аутентификации, которая может выступать в качестве OIDC-клиента для Keycloak. В этой архитектуре настройте URI перенаправления Keycloak как https://auth.example.com/upstream/callback/<provider-id>, где идентификатор поставщика соответствует конфигурации MAS. Настройте поставщика в разделе MAS upstream_oauth2.providers; затем Element использует поток аутентификации на основе MAS домашнего сервера. Не используйте Synapse /_synapse/client/oidc/callbackдля этого подключения к вышестоящему серверу. MAS требует поставщика OIDC, поддерживающего поток кода авторизации. Формат его конфигурации, необходимый идентификатор поставщика и шаги миграции отличаются от встроенного в Synapse oidc_providers.

Распространенные заблуждения и способы их исправления

• «Мне нужно всего лишь изменить конфигурацию Element». Element управляет потоком браузера, а Synapse или MAS обрабатывают OIDC. Сначала настройте правильный поставщик на стороне домашнего сервера.
• «Успешный вход в Keycloak подтверждает правильность сопоставления учетных записей». Аутентификация может пройти успешно, даже если выбрано неверное утверждение localpart или профиля. Протестируйте с пользователем, не работающим в производственной среде, и проверьте полученный идентификатор матрицы.
• «Система единого входа (SSO) автоматически отключает пароли и регистрацию». Эти политики контролируются домашним сервером и развертыванием. Проверьте настройки входа и регистрации Synapse отдельно и подтвердите утвержденную политику.
• «Выход из Element приводит к выходу из системы везде». Сессии браузера могут оставаться активными в Keycloak. Настройте и протестируйте выход из системы через обратный канал, если требуется централизованное завершение сессии.

Контрольный список проверки

• Клиент Keycloak использует поток авторизационного кода, аутентификацию клиента и точный обратный вызов для Synapse или MAS.
• URL-адрес эмитента соответствует метаданным обнаружения области, а секретный ключ клиента хранится на стороне сервера.
• Synapse или MAS запускаются без ошибок конфигурации OIDC и предоставляют доступ к предполагаемому методу входа в систему.
• Тестовый пользователь может войти в систему с новой сессии браузера, попасть в ожидаемую учетную запись Matrix и завершить обычную сессию Element.
• Правила выхода из системы, существующие учетные записи, ограничения регистрации и любой резервный доступ администратора должны соответствовать вашей политике.

Официальные ссылки

• Руководство по подключению OpenID в Synapse v1.144, включая настройки клиента Keycloak и функции обратного вызова.
• Конфигурация веб-элемента: параметры перенаправления SSO
• Служба аутентификации Matrix: настройка вышестоящего поставщика SSO
• Руководство по администрированию сервера Keycloak 26.8.0