Como configurar aliases de salas Matrix personalizados no seu domínio

Um alias de sala no Matrix atribui a uma sala um endereço legível por humanos, como #support:example.org`https://example.com/api/`. A parte após os dois pontos é o nome do servidor do homeserver , o domínio que detém o namespace do alias. Não se trata de um rótulo de domínio arbitrário que pode ser alterado adicionando um registro DNS. Para usar seu próprio domínio, seu homeserver deve ser configurado com esse domínio como nome de servidor; a federação pode então ser delegada a um host separado.

Este guia usa example.orgcomo domínio, matrix.example.orgcomo host do Synapse e #support:example.orgcomo alias de destino. Substitua esses espaços reservados pelos seus próprios valores. Ele se concentra no Synapse auto-hospedado. Se você usa um provedor Matrix hospedado, verifique se ele permite o uso de um nome de servidor personalizado; muitas contas hospedadas permitem a criação de aliases apenas no domínio do provedor.

O que faz um alias de sala Matrix

Um servidor doméstico é o servidor Matrix que armazena os dados das salas dos usuários e se conecta a outros servidores. Um ID de sala , como !opaqueid:example.org`<room_id>`, identifica tecnicamente uma sala. Um alias de sala , como ` #support:example.org<room_alias>`, é uma entrada de diretório legível que resolve para um ID de sala e uma lista de servidores que podem ajudar um usuário a entrar.

Um alias não renomeia a sala, não altera sua privacidade nem garante que ela apareça em um diretório público de salas. Essas são configurações separadas da sala. A sala pode ter vários aliases. Um alias canônico é o endereço preferencial exibido ou compartilhado pelos clientes; ele é publicado como estado da sala, enquanto o servidor doméstico mantém o mapeamento de alias para sala. A especificação Matrix alerta que os mapeamentos de alias podem mudar, portanto, resolva um endereço antes de confiar nele.

Antes de começar

• Controle o domínio que deseja usar, como por exemplo example.org, , incluindo a capacidade de fornecer conteúdo HTTPS nesse domínio.
• Execute um servidor doméstico como o Synapse com sua Matriz server_namedefinida como example.org. Esse valor é escolhido durante a configuração do servidor e não deve ser alterado posteriormente sem necessidade: IDs de usuário e aliases o utilizam como seu namespace.
• É necessário ter um certificado TLS e uma rota de federação válidos. O host Matrix delegado, como por exemplo matrix.example.org, deve apresentar um certificado válido.
• Para entrar na sala e ter a permissão necessária para alterar os endereços, o Synapse também possui regras no servidor que permitem ou negam a criação de aliases.

Se o servidor já estiver em execução com um nome diferente, por exemplo provider.net, criar um novo #support:example.orgnão é um atalho para mapeamento de domínio. Consulte o provedor sobre suporte a domínios personalizados ou planeje uma implantação e migração separadas para o servidor doméstico. O Matrix não define um processo para que um servidor doméstico crie aliases no namespace de outro servidor.

Passo 1: Escolha o nome do servidor e a rota de federação.

Antes de configurar o servidor doméstico, decida qual nome aparecerá após os dois pontos. Neste exemplo, o Synapse usa `<nome_do_servidor>` example.orgcomo nome do servidor, enquanto seus serviços de cliente e federação são executados em ` <nome_do_servidor>`. matrix.example.orgUm registro DNS envia o tráfego para ` matrix.example.org<nome_do_servidor>` para o host ou proxy reverso. O registro DNS por si só não estabelece o namespace do alias; o nome do servidor do Synapse é que o faz.

Quando o servidor doméstico não estiver diretamente acessível example.orgna porta de federação padrão 8448, o Matrix precisa de uma maneira de descobrir seu ponto de extremidade de federação. Um método comum é a delegação .well-known : uma pequena resposta JSON HTTPS no domínio do nome do servidor direciona o tráfego de federação para o host Matrix real. Sirva isso em https://example.org/.well-known/matrix/server:

{
  "m.server": "matrix.example.org:443"
}

Certifique-se de que a resposta seja um JSON válido, servida via HTTPS, e que o host de destino possua um certificado válido e encaminhe as solicitações de federação para o Synapse. A porta pode ser omitida quando o endpoint de federação utiliza a porta 8448; neste exemplo, a porta 443 é explícita. Se o Synapse já estiver servindo a federação no domínio do nome do servidor na porta 8448, a delegação pode não ser necessária. O /.well-known/matrix/clientarquivo voltado para o cliente é um mecanismo de descoberta diferente e não substitui a delegação do servidor.

A documentação de configuração atual do Synapse inclui a serve_server_wellknownopção para casos em que as solicitações para o domínio `server-name` na porta 443 são roteadas para o Synapse. Use essa opção somente se o seu proxy e o roteamento de domínio atenderem aos requisitos documentados. Caso contrário, configure a resposta JSON no seu servidor web ou proxy.

Etapa 2: Verifique as políticas de alias do Synapse

O Synapse pode restringir quem pode criar aliases e quais endereços de sala são permitidos. Em homeserver.yaml`<nome_da_lista>`, verifique alias_creation_rulesse uma solicitação de criação de alias foi negada. O Synapse avalia as regras configuradas em ordem; a primeira regra correspondente decide a solicitação e, se nenhuma regra corresponder, a solicitação é negada. Uma lista vazia nega todas as solicitações de criação de aliases. Uma lista nula ou omitida permite a criação de aliases por padrão, sujeita a outras verificações.

Verifique também require_membership_for_aliasesa configuração padrão, que exige que o usuário esteja na sala. Se você alterar a configuração do Synapse, siga o processo normal de validação e reinicialização da sua implementação e evite flexibilizar as políticas mais do que o necessário. Os níveis de privilégios da sala e os controles disponíveis no cliente também podem afetar se um membro comum pode definir o alias preferencial.

Passo 3: Crie um apelido para a sala.

Entre na sala desejada em um cliente Matrix e abra as configurações da sala. Procure por uma seção de endereço ou alias; a nomenclatura e o layout do cliente podem variar conforme a versão. Insira o endereço completo, incluindo o prefixo #e o domínio do servidor, por exemplo #support:example.org, . Adicione-o como endereço da sala e, se o cliente oferecer a opção, defina-o como o alias canônico ou preferencial. Salve as alterações.

Se o seu cliente não fornecer um controle de alias, uma solicitação de API cliente-servidor pode criar o mapeamento. O PUT /_matrix/client/v3/directory/room/{roomAlias}endpoint autenticado requer um ID de sala no corpo da solicitação. Por exemplo, um membro autorizado da sala ou uma conta de servidor pode enviar uma solicitação para o servidor principal que possui example.org:

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

Substitua o ID da sala de exemplo pelo ID exato da sala e use um token de acesso válido com a autorização necessária. Trate o token como uma senha: não o publique, não o cole em uma postagem de suporte nem o inclua em um sistema de controle de versão. Verifique os caracteres de escape de porcentagem na codificação da URL #e :no caminho HTTP. Uma resposta bem-sucedida indica que o mapeamento foi criado. Uma resposta "já existe" significa que o nome está ocupado; confirme quem é o proprietário antes de alterar ou remover qualquer informação.

Passo 4: Verifique o endereço e compartilhe-o.

Resolva o alias usando a API pública cliente-servidor. Esta consulta não requer autenticação:

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

Uma resposta bem-sucedida deve conter o alias esperado room_ide uma serverslista. Compare o ID da sala retornado com o ID da sala desejada. Um erro 404 significa que o alias não possui um mapeamento no servidor que gerencia esse namespace. Um erro 400 indica um endereço formatado incorretamente. Em seguida, teste o alias completo em uma segunda conta ou cliente Matrix para confirmar se a sala é resolvida e se é possível entrar nela de acordo com suas regras de entrada.

Se você definir um alias canônico, verifique novamente os detalhes da sala e confirme se o endereço preferencial é o que você pretende publicar. Compartilhe o alias ou um link permanente do Matrix somente após confirmar que ele direciona para a sala correta. Lembre-se de que um alias público não torna uma sala privada pública; o usuário ainda precisa de permissão para entrar.

Problemas comuns a evitar

• Ao usar um domínio que não pertence ao servidor principal: o nome do servidor em um alias deve corresponder ao namespace do servidor principal que o criou. Um registro CNAME de DNS sozinho não pode autorizar o domínio de outro servidor.
• Confundir domínio e host: ` example.org <nome_do_servidor>` pode ser o namespace do alias, enquanto `< matrix.example.orghost_do_serviço>` é o host do serviço. Defina o nome do servidor Synapse e a delegação de forma consciente.
• Colocar o arquivo de descoberta do cliente no local errado: a delegação de federação usa /.well-known/matrix/servero arquivo `clientdiscovery.yaml`. O arquivo de descoberta do cliente tem um caminho e uma finalidade diferentes.
• Supondo que um alias publique uma sala publicamente: a resolução de aliases e a publicação no diretório público de salas são operações separadas, regidas por políticas distintas.
• Alterar o nome do servidor em uma implantação já estabelecida: os IDs do Matrix existentes dependem desse namespace. Trate uma alteração de domínio como uma migração arquitetural, não como uma simples configuração de alias.
• Compartilhamento sem verificar o mapeamento: resolva o alias e compare o ID da sala retornado antes de publicar. Um endereço legível é conveniente, mas o mapeamento do servidor é o que determina para onde ele leva.

Para obter detalhes sobre o protocolo, consulte o formato de identificador e alias do Matrix e a API de alias de sala do Matrix . Para configurar o Synapse, consulte o guia de delegação de federação e o manual de configuração do Element . As opções e telas do cliente Synapse podem mudar entre versões; verifique a documentação da versão que você utiliza.