Conecte o Element Web ao Keycloak por meio do OIDC do Synapse.

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.

Deixar um comentário

Resolver erros de permissão de administrador de salas Matrix por meio de ação

Rastreie a variável de ambiente M_FORBIDDEN até os níveis de poder da sala, a associação ou o acesso de administrador do servidor Synapse e, em seguida, restaure apenas a permissão necessária para a ação bloqueada.

Torne seu servidor Matrix Synapse acessível para federação.

Torne seu servidor Matrix Synapse acessível para federação.

Configure a descoberta do Synapse, o HTTPS e o roteamento de proxy para que outros servidores domésticos Matrix possam encontrar e contatar o seu servidor.

Conecte o Element Web ao Keycloak por meio do OIDC do Synapse.

Configure um cliente OIDC Keycloak e um provedor Synapse para que os usuários do Element Web possam fazer login por meio do seu servidor de identidade sem expor segredos do cliente.

Configure o backup e a assinatura cruzada da chave do elemento com segurança.

Configure o backup e a assinatura cruzada da chave do elemento com segurança.

Salve uma chave de recuperação, verifique suas sessões do Element e certifique-se de que as chaves de mensagens criptografadas possam ser restauradas sem confundir o backup com a senha da sua conta.

Pare as falhas de memória do Matrix Synapse durante a sincronização do cliente.

Diagnosticar falhas de falta de memória do Synapse durante a sincronização, ajustar o cache com segurança, identificar atrasos nas solicitações e verificar o uso estável da memória.

Resolver erros de certificado TLS da Synapse Federation

Rastreie falhas de certificado de federação do Trace Matrix para o servidor correto, repare a cadeia TLS ou a confiança da CA e verifique a correção sem desativar as verificações de segurança.

Coloque um servidor Synapse Matrix atrás do Cloudflare com segurança.

Coloque um servidor Synapse Matrix atrás do Cloudflare com segurança.

Os clientes do Route Matrix e a federação através do Cloudflare em HTTPS 443 preservam a descoberta do Synapse e evitam o armazenamento em cache do tráfego da API ou a interrupção de uploads de mídia.

Restaure o Matrix Synapse com segurança usando um dump do PostgreSQL.

Faça backup do Synapse com pg_dump, proteja sua chave de assinatura e mídia e restaure-o em um banco de dados PostgreSQL limpo, sem reutilizar chaves de uso único obsoletas.

Execute o Mjölnir como um bot de moderação de salas Matrix com Docker.

Execute o Mjölnir como um bot de moderação de salas Matrix com Docker.

Configure o Mjölnir com uma conta Matrix dedicada, sala de gerenciamento criptografada, Docker Compose, lista de políticas e verificações de permissão.

Ative a sincronização deslizante nativa da matriz para um carregamento mais rápido em dispositivos móveis.

Ative a sincronização deslizante nativa da matriz para um carregamento mais rápido em dispositivos móveis.

Ignore o proxy descontinuado e configure a Sincronização Deslizante integrada do Synapse. Verifique a descoberta de clientes e, em seguida, meça o carregamento da lista de salas e o comportamento de reconexão em um telefone compatível.