Come configurare alias personalizzati per le stanze Matrix sul tuo dominio

Un alias di stanza Matrix assegna a una stanza un indirizzo leggibile dall'uomo, come ad esempio . La parte dopo i due punti è il nome del server#support:example.org dell'homeserver , ovvero il dominio proprietario dello spazio dei nomi dell'alias. Non si tratta di un'etichetta di dominio arbitraria che può essere modificata aggiungendo un record DNS. Per utilizzare il proprio dominio, l'homeserver deve essere configurato con tale dominio come nome del server; la federazione può quindi essere delegata a un host separato.

Questa guida utilizza example.orgcome dominio, matrix.example.orgcome host Synapse e #support:example.orgcome alias di destinazione. Sostituisci questi segnaposto con i tuoi valori. Si concentra su Synapse self-hosted. Se utilizzi un provider Matrix ospitato, verifica se ti consente di utilizzare un nome server personalizzato; molti account ospitati possono creare alias solo con il dominio del provider.

Che cosa fa un alias di stanza Matrix

Un homeserver è il server Matrix che memorizza i dati delle stanze degli utenti e si connette ad altri server. Un ID stanza , come ad esempio !opaqueid:example.org, identifica tecnicamente una stanza. Un alias stanza , come ad esempio #support:example.org, è una voce di directory leggibile che si risolve in un ID stanza e in un elenco di server che possono aiutare un utente ad accedervi.

Un alias non rinomina la stanza, non ne modifica la privacy né garantisce la sua presenza in una directory pubblica delle stanze. Queste sono impostazioni separate della stanza. Una stanza può avere più alias. Un alias canonico è l'indirizzo preferito visualizzato o condiviso dai client; viene pubblicato come stato della stanza, mentre l'homeserver gestisce la mappatura alias-stanza. La specifica Matrix avverte che le mappature degli alias possono cambiare, quindi è necessario risolvere un indirizzo prima di farvi affidamento.

Prima di iniziare

• Controlla il dominio che desideri utilizzare, ad esempio example.org, inclusa la possibilità di servire contenuti HTTPS su tale dominio.
• Avvia un homeserver come Synapse con la sua matrice server_nameimpostata su example.org. Questo valore viene scelto durante la configurazione del server e non dovrebbe essere modificato casualmente in seguito: gli ID utente e gli alias lo utilizzano come namespace.
• È necessario disporre di un certificato TLS funzionante e di una rotta di federazione. L'host Matrix delegato, ad esempio matrix.example.org, deve presentare un certificato valido.
• Devi essere connesso alla stanza e disporre delle autorizzazioni necessarie per modificarne gli indirizzi. Synapse dispone anche di regole lato server che possono consentire o negare la creazione di alias.

Se il server è già in esecuzione con un nome server diverso, ad esempio provider.net, la creazione #support:example.orgnon è una scorciatoia per la mappatura del dominio. Chiedi al provider informazioni sul supporto per domini personalizzati o pianifica una distribuzione e migrazione separate dell'homeserver. Matrix non definisce una procedura per la creazione di alias da parte di un homeserver nello spazio dei nomi di un altro server.

Passaggio 1: Scegliere il nome del server e il percorso di federazione

Prima di configurare l'homeserver, decidi quale nome apparirà dopo i due punti. In questo esempio, Synapse utilizza example.orgcome nome del server, mentre i servizi client e di federazione vengono eseguiti all'indirizzo matrix.example.org. Un record DNS instrada il traffico per matrix.example.orgall'host o al proxy inverso. Il record DNS di per sé non stabilisce lo spazio dei nomi alias; lo fa il nome del server di Synapse.

Quando il server principale non è raggiungibile direttamente example.orgsulla porta di federazione predefinita 8448, Matrix ha bisogno di un modo per scoprire il suo endpoint di federazione. Un metodo comune è la delega .well-known : una piccola risposta JSON HTTPS sul dominio server-name indirizza il traffico di federazione all'host Matrix effettivo. Servire questa risposta a https://example.org/.well-known/matrix/server:

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

Assicurarsi che la risposta sia in formato JSON valido, servita tramite HTTPS e che l'host di destinazione disponga di un certificato valido e instradi le richieste di federazione a Synapse. La porta può essere omessa quando l'endpoint di federazione utilizza la porta 8448; in questo esempio, la porta 443 è specificata esplicitamente. Se Synapse gestisce già la federazione sul dominio server-name sulla porta 8448, la delega potrebbe non essere necessaria. Il /.well-known/matrix/clientfile lato client è un meccanismo di rilevamento diverso e non sostituisce la delega lato server.

La documentazione di configurazione attuale di Synapse include serve_server_wellknownun'opzione per i casi in cui le richieste al dominio server-name sulla porta 443 vengono instradate a Synapse. Utilizzare tale opzione solo se il proxy e l'instradamento del dominio corrispondono ai requisiti documentati. In caso contrario, configurare la risposta JSON sul server web o sul proxy.

Passaggio 2: Verifica le policy sugli alias di Synapse

Synapse può limitare chi può creare alias e quali indirizzi di stanza sono consentiti. In homeserver.yaml, verifica alias_creation_rulesse una richiesta di creazione di alias viene rifiutata. Synapse valuta le regole configurate in ordine; la prima regola corrispondente decide la richiesta e, se nessuna regola corrisponde, la richiesta viene rifiutata. Un elenco vuoto rifiuta tutte le richieste di creazione di alias. Un elenco nullo o omesso consente la creazione di alias per impostazione predefinita, previa verifica di altri aspetti.

Verifica anche require_membership_for_aliases, che per impostazione predefinita richiede che l'utente sia presente nella stanza. Se modifichi la configurazione di Synapse, segui la normale procedura di convalida e riavvio della tua implementazione ed evita di allentare le policy più del necessario. Anche i livelli di potenza di una stanza e i controlli disponibili del client possono influire sulla possibilità per un membro normale di impostare l'alias preferito.

Passaggio 3: crea un alias per la stanza

Accedi alla stanza desiderata tramite un client Matrix e apri le impostazioni della stanza. Cerca la sezione relativa all'indirizzo o all'alias; la terminologia e il layout del client possono variare a seconda della versione. Inserisci l'indirizzo completo, inclusi il #dominio principale e quello del server principale, ad esempio #support:example.org. Aggiungilo come indirizzo della stanza e, se il client lo consente, impostalo come alias canonico o preferito. Salva la modifica.

Se il client non fornisce un controllo alias, è possibile creare la mappatura tramite una richiesta API client-server. L' PUT /_matrix/client/v3/directory/room/{roomAlias}endpoint autenticato richiede un ID stanza nel corpo della richiesta. Ad esempio, un membro autorizzato della stanza o un account server può inviare una richiesta al server principale proprietario di 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"}'

Sostituisci l'ID della stanza di esempio con l'ID esatto della stanza e utilizza un token di accesso valido con l'autorizzazione necessaria. Tratta il token come una password: non pubblicarlo, non incollarlo in un post di supporto e non inserirlo nel sistema di controllo versione. Il carattere percentuale viene utilizzato per la codifica URL #e :per il percorso HTTP. Una risposta positiva indica che la mappatura è stata creata. Una risposta "già esistente" significa che il nome è già occupato; verifica chi ne è il proprietario prima di apportare modifiche o rimuovere qualsiasi elemento.

Passaggio 4: Verifica l'indirizzo e condividilo

Risolvi l'alias utilizzando l'API client-server pubblica. Questa ricerca non richiede autenticazione:

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

Una risposta positiva dovrebbe contenere le informazioni previste room_ide un serverselenco. Confronta l'ID della stanza restituito con la stanza desiderata. Un errore 404 significa che l'alias non ha una mappatura sul server che gestisce quello spazio dei nomi. Un errore 400 punta a un indirizzo formattato in modo non valido. Quindi, testa l'alias completo in un secondo account o client Matrix per confermare che la stanza venga risolta e che sia possibile accedervi in ​​base alle sue regole di accesso.

Se imposti un alias canonico, ricontrolla i dettagli della stanza e conferma che l'indirizzo preferito sia quello che intendi pubblicare. Condividi l'alias o un permalink Matrix solo dopo aver verificato che si risolva nella stanza corretta. Ricorda che un alias pubblico non rende pubblica una stanza privata; un utente ha comunque bisogno dell'autorizzazione per accedervi.

Problemi comuni da evitare

• Utilizzo di un dominio non di proprietà del server principale: il nome del server in un alias deve corrispondere allo spazio dei nomi del server principale che lo crea. Un record CNAME DNS da solo non è sufficiente ad autorizzare il dominio di un altro server.
• Confondere il dominio con l'host: example.org può essere lo spazio dei nomi alias mentre matrix.example.orgè l'host del servizio. Impostare il nome del server Synapse e la delega con attenzione.
• Posizionamento errato del file di individuazione del client: la delega di federazione utilizza /.well-known/matrix/server. Il file di individuazione del client ha un percorso e uno scopo diversi.
• Supponendo che un alias pubblichi una stanza pubblicamente: la risoluzione dell'alias e la pubblicazione della directory delle stanze pubbliche sono operazioni separate, regolate da politiche separate.
• Modifica del nome del server in una distribuzione esistente: gli ID Matrix esistenti dipendono da quello spazio dei nomi. Considera la modifica del dominio come una migrazione architetturale, non come una semplice impostazione di un alias.
• Condivisione senza verificare la mappatura: risolvi l'alias e confronta l'ID della stanza restituito prima di pubblicarlo. Un indirizzo leggibile è comodo, ma è la mappatura del server che determina la destinazione.

Per i dettagli del protocollo, consultare il formato dell'identificativo e dell'alias di Matrix e l' API degli alias delle stanze di Matrix . Per la configurazione di Synapse, consultare la guida alla delega della federazione e il manuale di configurazione di Element . Le opzioni di Synapse e le schermate client possono variare tra le diverse versioni; consultare la documentazione relativa alla versione in uso.