O Element Web não se autentica diretamente no Keycloak. O Element consulta seu servidor Matrix para obter os métodos de login suportados; o servidor Matrix completa a conexão OpenID Connect (OIDC) com o Keycloak e retorna o usuário para o Element. Para uma implementação do Synapse usando seu suporte OIDC integrado, configure um cliente OIDC confidencial no Keycloak, adicione esse provedor ao Synapse e, opcionalmente, ajuste as configurações do Element Web config.jsonpara exibir ou iniciar o SSO automaticamente.
Este guia utiliza o provedor OIDC integrado do Synapse, que é um método de implementação comum. Se o seu servidor doméstico delega a autenticação ao Matrix Authentication Service (MAS), utilize a configuração de retorno de chamada e provedor do MAS descrita abaixo. Os dois URLs de retorno de chamada são diferentes. As instruções foram verificadas em relação à documentação de configuração do Element Web, ao guia OIDC do Synapse v1.144, ao guia SSO upstream atual do MAS e ao guia de administração do Keycloak 26.8.0 em 6 de outubro de 2026; o pacote de implementação e os rótulos da interface do usuário podem variar de acordo com a versão.
| Implantação | Onde o Keycloak está configurado | URL de retorno de chamada do Keycloak |
|---|---|---|
| OIDC integrado do Synapse | Sinapseoidc_providers | https://matrix.example.com/_synapse/client/oidc/callback |
| O Synapse delega a autorização ao MAS. | MASupstream_oauth2.providers | https://auth.example.com/upstream/callback/<provider-id> |
Verifique a documentação de configuração e implantação do Synapse antes de criar um cliente. O retorno de chamada deve pertencer ao componente que se comunica com o Keycloak; não registre a URL do site do Element como retorno de chamada.
https://matrix.example.com, e um emissor de realm Keycloak acessível, como https://sso.example.com/realms/company.No domínio usado para contas Matrix, crie um cliente para o Synapse usando o protocolo OpenID Connect. Habilite o código de autorização ou o fluxo padrão e a autenticação do cliente para que o Synapse possa usar um segredo do cliente no endpoint do token. Defina o ID do cliente para um valor que você também usará no Synapse, por exemplo synapse.
Defina o URI de redirecionamento válido para o callback exato do Synapse:
https://matrix.example.com/_synapse/client/oidc/callbackSubstitua o nome de host de exemplo pela URL base pública realmente configurada para o Synapse. Não use um curinga amplo como *em produção. O Keycloak valida URIs de redirecionamento, portanto, uma incompatibilidade de host, esquema, caminho ou barra invertida no final pode causar um erro de "URI de redirecionamento não permitida".
Salve o cliente, copie o segredo gerado e armazene-o como um segredo do lado do servidor. Mantenha-o fora do diretório público do Element Web config.json, do controle de versão, das capturas de tela e do JavaScript do lado do cliente. O console de administração do Keycloak pode rotular a autenticação ou as credenciais do cliente de forma diferente em cada versão; verifique se o cliente resultante é confidencial e pode usar o fluxo de código de autorização padrão.
O emissor identifica o domínio, não a raiz do servidor Keycloak. Para este exemplo, use `<nome_do_domínio>` https://sso.example.com/realms/company. Confirme se a configuração OpenID do domínio está acessível em ` <issuer>/.well-known/openid-configuration<nome_do_domínio>` e se o emissor anunciado corresponde exatamente ao valor que você fornecerá ao Synapse.
O Synapse precisa de uma declaração de identidade estável para associar a conta do Keycloak a um usuário do Matrix. Seu provedor OIDC normalmente identifica o sujeito externo usando a declaração de sujeito OIDC; o mapeamento de nome de usuário abaixo usa preferred_usernameessa declaração como a parte local do Matrix. Certifique-se de que o Keycloak realmente retorne essa declaração e que os nomes de usuário sejam únicos e estáveis de acordo com a política da sua conta. Se sua organização permite alterações de nome de usuário, escolha e teste uma estratégia de mapeamento antes da produção; uma alteração inesperada no mapeamento pode afetar a qual conta do Matrix uma pessoa é acessada.
Adicione uma entrada de provedor à configuração principal do Synapse, geralmente em `.synapse.yaml` homeserver.yaml. Mescle-a com o YAML existente em vez de substituir outras configurações. Substitua o emissor do seu domínio e o segredo do cliente real:
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 }}"Os escopos solicitados controlam quais informações do usuário o Keycloak pode retornar; eles não garantem que todas as declarações sejam preenchidas. Se você não precisar importar e-mails ou nomes de exibição, reduza os escopos e o mapeamento de acordo. Mantenha o arquivo de configuração legível apenas pelo administrador do serviço e pelo processo do Synapse, conforme apropriado para sua implantação. Se você gerencia o Synapse por meio de contêineres ou um gráfico, coloque as configurações do provedor na fonte de configuração compatível, em vez de editar um arquivo gerado que será sobrescrito.
Por padrão, encerrar a sessão de um serviço não encerra necessariamente a sessão do navegador de todos os outros serviços. Se você deseja que as notificações de logout do Keycloak encerrem a sessão do Synapse, habilite-as backchannel_logout_enabled: trueno provedor Keycloak no Synapse e defina o URL de logout do canal de retorno do Keycloak para:
https://matrix.example.com/_synapse/client/oidc/backchannel_logoutIsso é opcional e depende da sua política de logout e da configuração do cliente. Teste as duas direções de logout: logout do Synapse e logout do Keycloak. Não presuma que o logout do Element por si só encerre a sessão do Keycloak.
Valide o arquivo YAML com as verificações de configuração da sua implantação e, em seguida, reinicie ou recarregue o Synapse usando o método compatível com a configuração do seu pacote ou contêiner. Analise os logs do Synapse em busca de erros de descoberta OIDC, autenticação do cliente, retorno de chamada ou mapeamento de declarações. Use uma conta de teste primeiro e confirme se o ID da Matriz e o nome de exibição correspondem aos valores esperados.
Assim que o Synapse anunciar o login OIDC, o Element Web poderá apresentar sua opção de login SSO. A configuração do Element sso_redirect_optionscontrola a experiência do navegador; ela não configura o Keycloak nem armazena o segredo do cliente. Adicione uma configuração como esta ao arquivo `server.xml` do Element Web config.jsonse desejar que visitantes não autenticados que chegam à página de boas-vindas ou de login sejam direcionados para o fluxo SSO disponível:
{
"sso_redirect_options": {
"immediate": false,
"on_welcome_page": true,
"on_login_page": true
}
}Para uma implementação que realmente exige login somente por SSO, configure "immediate": trueo SSO para ser ativado para todos os usuários não autenticados. Isso pode dificultar o acesso a senhas ou outras opções de login, portanto, teste a recuperação de senha e o acesso administrativo antes de implementá-lo. Se os usuários precisarem escolher entre o SSO e outro método, deixe o redirecionamento automático desativado e verifique se a opção SSO aparece no fluxo de login.
O MAS é um serviço de autenticação separado e pode atuar como cliente OIDC para o Keycloak. Nessa arquitetura, configure o URI de redirecionamento do Keycloak como `<username>` https://auth.example.com/upstream/callback/<provider-id>, onde o ID do provedor corresponde à configuração do MAS. Configure o provedor no `<username>` do MAS upstream_oauth2.providers; o Element então usa o fluxo de autenticação baseado em MAS do servidor doméstico. Não use o `<username>` do Synapse /_synapse/client/oidc/callbackpara essa conexão upstream. O MAS requer um provedor OIDC que suporte o fluxo de código de autorização. Seu formato de configuração, ID do provedor necessário e etapas de migração são distintos do `<username>` integrado do Synapse oidc_providers.
Diagnostique picos de uso da CPU no navegador do Jitsi Meet e reduza a carga do cliente verificando os mosaicos de vídeo, os efeitos da câmera, os gráficos do navegador e as configurações do host.
Monitore a integridade, a carga da conferência e o tráfego do Jitsi Videobridge com seu endpoint Prometheus integrado e, em seguida, explore e visualize os dados em gráficos no Grafana.
Configure um domínio personalizado para o Jitsi Meet Docker com DNS, URL pública, HTTPS, Let's Encrypt, portas de firewall, configurações de NAT e verificação de ponta a ponta.
Corrija os erros 404 do Console de Administração do Zimbra após a renovação do SSL, verificando o URL e a porta corretos, o roteamento do proxy, o status do serviço, os certificados implantados e os logs.
Aprenda a diagnosticar e corrigir o aviso de configuração do PHP OPcache do Nextcloud, verificando o PHP SAPI ativo, os limites de tamanho, os comentários e as configurações de revalidação.
Solucione problemas de falhas na migração do banco de dados Kopano após uma atualização do MySQL ou MariaDB, verificando backups, versões do servidor, modos SQL, conjunto de caracteres, estado do esquema e logs.
Conecte o Nextcloud ao LDAP ou Active Directory com transporte seguro, filtros de usuários e grupos, atributos de login e uma implementação testada.
Corrija as notificações do Element no Android em telefones sem serviços do Google configurando o UnifiedPush, as permissões do Android, as configurações de bateria e realizando testes de verificação confiáveis.
Remova o aviso de índices de banco de dados ausentes do Nextcloud com o comando oficial occ. Primeiro, faça um backup, visualize as alterações, execute o reparo e verifique o resultado.
Configure o SSO do Keycloak para o Element Web conectando o OIDC ao Synapse, definindo a URL de retorno de chamada exata, mapeando as declarações do usuário e testando o logout.
