Como configurar o Single Sign-On (SSO) com o Keycloak no Element Web

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.

Primeiro, identifique qual caminho de autenticação você utiliza.

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.

Do que você precisa

• Um URL HTTPS público para o Synapse, como https://matrix.example.com, e um emissor de realm Keycloak acessível, como https://sso.example.com/realms/company.
• Acesso administrativo ao domínio Keycloak e à configuração e serviço do Synapse.
• Um backup da configuração atual e uma forma de usar os logs do Synapse ou um console do servidor caso o login falhe.
• Uma decisão sobre o provisionamento de contas: quais usuários do Keycloak podem fazer login, qual declaração os identifica e se as contas Matrix existentes devem ser mantidas.

Configure o Keycloak para o Synapse OIDC.

1. Criar um cliente OIDC confidencial

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/callback

Substitua 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.

2. Confirme o emissor e as reivindicações.

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.

Configurar Synapse

3. Adicione o provedor OIDC

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.

4. Opcionalmente, configure o logout por canal secundário.

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_logout

Isso é 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.

5. Reinicie e teste o Synapse.

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.

Configurar Elemento Web

6. Mantenha o SSO opcional ou redirecione automaticamente.

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.

Se o Synapse usar o serviço de autenticação Matrix

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.

Mal-entendidos comuns e soluções

• "Só preciso alterar a configuração do Element." O Element controla o fluxo do navegador, enquanto o Synapse ou o MAS lidam com o OIDC. Configure primeiro o provedor correto no servidor doméstico.
• “Um login bem-sucedido no Keycloak comprova que o mapeamento da conta está correto.” A autenticação pode ser bem-sucedida mesmo que a parte local ou a declaração de perfil selecionada esteja incorreta. Teste com um usuário que não esteja em produção e verifique o ID da Matrix resultante.
• “O SSO desativa automaticamente senhas e cadastros.” Essas políticas são controladas pelo servidor principal e pela implantação. Analise as configurações de login e cadastro do Synapse separadamente e confirme a política aprovada.
• “Sair do Element me desconecta de todos os lugares.” As sessões do navegador podem permanecer ativas no Keycloak. Configure e teste o logout por canal alternativo caso seja necessário o encerramento centralizado da sessão.

Lista de verificação

• O cliente Keycloak utiliza o fluxo de código de autorização, autenticação do cliente e o retorno de chamada exato para Synapse ou MAS.
• A URL do emissor corresponde aos metadados de descoberta do domínio, e o segredo do cliente é armazenado no servidor.
• O Synapse ou MAS inicia sem erros de configuração OIDC e expõe o método de login pretendido.
• Um usuário de teste pode fazer login a partir de uma nova sessão do navegador, acessa a conta Matrix esperada e consegue concluir uma sessão normal do Element.
• O comportamento de encerramento de sessão, as contas existentes, as restrições de registo e qualquer acesso de administrador alternativo devem estar em conformidade com a sua política.

Referências oficiais

• Guia do Synapse v1.144 para OpenID Connect, incluindo configurações do cliente Keycloak e de retorno de chamada.
• Configuração do Element Web: opções de redirecionamento SSO
• Serviço de Autenticação Matrix: configurando um provedor SSO upstream
• Guia de Administração do Servidor Keycloak 26.8.0