Para adicionar o login do Keycloak ao Element Web, configure o Keycloak como um provedor OpenID Connect (OIDC) no Synapse e certifique-se de que o Element Web esteja usando esse servidor Synapse. O Synapse lida com o redirecionamento e o retorno de chamada de autenticação; o Element Web não precisa do segredo do cliente Keycloak.
Exemplo de cenário (hipotético): uma pequena organização executa o Element Web em chat.example.org, o Synapse em matrix.example.orge o Keycloak em login.example.org. A mesma sequência se aplica a outros nomes de host, mas cada URL deve corresponder à sua configuração pública real. Este exemplo é ilustrativo e não representa um cenário de configuração real.
O que você precisa saber antes de alterar as configurações.
Use URLs HTTPS públicas para Keycloak e Synapse. A documentação OIDC do Synapse exige uma origem segura para o provedor de identidade, e seu retorno de chamada deve ser acessível através da URL pública do Synapse. Confirme o nome do domínio no Keycloak, no Synapse public_baseurle na URL do servidor doméstico fornecida ao Element Web. Se um proxy reverso estiver na frente de qualquer um dos serviços, ele deve encaminhar as solicitações para o backend correto e preservar o host e o esquema HTTPS externos.
A configuração atual do Synapse usa uma oidc_providerslista. O formato antigo com um único provedor oidc_configestá obsoleto. Mantenha um login de administrador funcional e uma cópia da configuração atual durante os testes. Não desative o login com senha ou o registro até que você tenha verificado o fluxo de SSO e decidido como as contas serão provisionadas.
1. Registre o Synapse como cliente no Keycloak.
No ambiente Keycloak onde os usuários da sua organização residem, crie um cliente OpenID Connect para o Synapse. O exemplo oficial do Keycloak no Synapse utiliza um cliente confidencial com o ID do cliente synapse. Defina o URI de redirecionamento válido para este callback exato, substituindo o nome do host do seu Synapse:
https://matrix.example.org/_synapse/client/oidc/callback
Para a configuração hipotética, defina o tipo de acesso do cliente como confidencial e habilite o cliente. Na guia Credenciais, copie o segredo do cliente gerado para o seu sistema de gerenciamento de segredos; não o coloque na pasta pública do Element Web config.jsonnem o publique em um repositório.
O URI de redirecionamento é uma fonte frequente de falhas. Ele deve usar a URL pública do Synapse, o /_synapse/client/oidc/callbackcaminho exato e o mesmo esquema e nome de host que o Synapse vê do navegador. Evite um callback com curinga genérico quando um URI exato funcionar. Se você habilitar o logout por canal secundário posteriormente, adicione também o endpoint de canal secundário documentado do Synapse no Keycloak; isso é opcional e independente do login básico.
2. Adicione o provedor Keycloak ao Synapse.
Edite o arquivo active homeserver.yaml. Substitua o realm e o secret abaixo pelos seus valores e confirme a URL do emissor no documento de descoberta OpenID do realm. O emissor padrão de um realm do Keycloak tem o seguinte formato:
https://login.example.org/realms/your-realm
Para uma implementação que utilize o endpoint de descoberta padrão e as declarações mostradas no exemplo do Keycloak da Synapse, a entrada do provedor é:
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 }}"
O emissor deve corresponder ao emissor do domínio do Keycloak, e não apenas à raiz do servidor Keycloak. A descoberta permite que o Synapse obtenha os endpoints de autorização, token e informações do usuário desse emissor. O mapeamento usa o do Keycloak preferred_usernamepara formar um localpart do Matrix e namecomo nome de exibição; certifique-se de que essas declarações estejam presentes e estáveis para seus usuários. Um localpart do Matrix é um identificador de conta, portanto, alterar o mapeamento posteriormente pode causar confusão na correspondência de contas ou gerar um ID do Matrix diferente.
Mantenha a lista existente oidc_providersse outros provedores de identidade estiverem configurados; adicione esta entrada em vez de substituir provedores não relacionados. Proteja o segredo do cliente como um segredo e defina as permissões de arquivo de acordo com sua implantação. Valide a indentação do YAML e reinicie o Synapse usando o procedimento de serviço ou contêiner da sua instalação. Instalações empacotadas podem já incluir dependências do OIDC; para uma instalação em ambiente virtual (virtualenv), a documentação do Synapse descreve a instalação matrix-synapse[oidc]. Siga as orientações do mantenedor do seu pacote para outros métodos de instalação.
3. Elemento Web de Ponto no mesmo servidor doméstico
O Element Web config.jsondeve identificar o servidor Synapse como seu servidor principal, por exemplo, através de `<nome_do_servidor>` default_server_config.mHomeserver.base_url. Use a URL real do servidor principal, não a do emissor do Keycloak. O Element Web é um cliente estático: após alterar a URL do servidor principal, reimplemente ou recarregue sua configuração usando seu método de hospedagem. Não coloque o segredo do cliente Keycloak neste arquivo, pois os navegadores podem lê-lo.
No exemplo hipotético, o Element Web está hospedado em `<endereço_do_servidor>` https://chat.example.orge se conecta a ` https://matrix.example.org<endereço_do_servidor>`. Quando um usuário seleciona a opção SSO na tela de login do Element, o navegador deve percorrer o fluxo de login do Synapse até o domínio do Keycloak e retornar ao callback do Synapse. A redação exata do botão e o layout da tela de login podem variar de acordo com a versão do Element Web e a configuração do servidor; teste o comportamento em vez de confiar em um rótulo específico.
4. Faça um teste com uma conta antes de implementar o SSO.
Abra o Element Web em uma janela anônima do navegador e selecione a opção de login SSO. Faça login com um usuário de teste do Keycloak, aprove o acesso solicitado, se necessário, e confirme se o navegador retorna ao servidor principal desejado e abre a conta Matrix esperada. Verifique se o ID do Matrix resultante contém a parte local correta. Analise os logs do Synapse e do Keycloak caso o navegador retorne algum erro.
Se o redirecionamento falhar, compare o URL de retorno de chamada no Keycloak, caractere por caractere, com o URL de retorno de chamada público do Synapse. Uma "incompatibilidade de emissor" indica um emissor de domínio ou nome de host de proxy reverso incorreto. Um nome de usuário ausente ou um erro de mapeamento significa que a declaração configurada está ausente ou inadequada; inspecione as declarações do usuário de teste e ajuste o mapeamento cuidadosamente. Se o navegador acessar o Keycloak, mas não retornar, verifique os certificados TLS e o roteamento do proxy para o retorno de chamada do Synapse.
Logout opcional: o Synapse oferece suporte ao logout via canal reverso OIDC. Para usá-lo, defina- backchannel_logout_enabled: trueo neste provedor e configure a URL de logout via canal reverso do Keycloak como https://matrix.example.org/_synapse/client/oidc/backchannel_logout. O Synapse também documenta a ativação da opção `session-required` no Keycloak. Isso lida com as notificações de logout iniciadas pelo provedor; não é necessário para que o login SSO inicial funcione.
Antes da implementação: decida se o SSO deve criar novos usuários do Matrix ou autenticar apenas as contas provisionadas separadamente e, em seguida, revise as opções de OIDC do Synapse para a versão instalada. Os rótulos de configuração e a interface de administração do Keycloak podem mudar entre as versões. As etapas descritas aqui seguem a documentação de OIDC do Synapse, disponível em 10 de outubro de 2026, e pressupõem um domínio Keycloak padrão e uma implementação do Synapse usando o formato de provedor documentado. Consulte o guia do Synapse OpenID Connect e Keycloak , a referência de configuração do Synapse e a documentação oficial do Keycloak antes de aplicar as configurações específicas da versão. Depois que a conta de teste fizer login corretamente e você tiver uma rota de recuperação, documente o retorno de chamada final, o emissor e o mapeamento de declarações para os administradores.