Skip to main content

Federation

Federation is the process by which users on different servers can participate in the same room. For this to work, those other servers must be able to contact yours to send messages.

When Federation is Open, you will not need to configure anything further, however to privately federate you will need to make use of the Federation section found under Advanced.

Client Minimum TLS Version

federation_client_minimum_tls_version

Allows you to choose the minimum TLS version that will be used for outbound federation requests. Defaults to "1.2". Configurable to "1.2" or "1.3".

Setting this value higher than "1.2" will prevent federation to most of the public Matrix network: only configure it to "1.3" if you have an entirely private federation setup and you can ensure TLS 1.3 support.

Certificate Autorities Secret Keys

Configure when you are federating between homeservers' whose certificates are signed by different Certiciate Authorities, click the Add Certificate Autorities Secret Keys / Add More Certificate Autorities Secret Keys button to reveal the option to upload your CA certificate.

Uploaded certificates should be PEM encoded and include the full chain of intermediate CAs and the root CA. You can simply concatenate these files prior to uploading.

Trusted Key Servers

'trusted_key_servers'

Used to specifify the trusted servers to download signing keys from. When synapse needs to fetch a signing key, each server is tried in parallel. Normally, the connection to the key server is validated via TLS certificates. Verify keys provide additional security by making synapse check that the response is signed by that key.

Click Add Trusted Key Servers / Add More Trusted Key Servers to add a new key server, then provide the homeservers' federated server name, i.e. the base domain of the homeserver you with to federate with. Under Verify Keys for the server, you will need to provide it's Key ID and Public Key.

Getting an On-Premise Homeservers' Key ID and Public Key via the Installer

You can retrieve the Public Key of an On-Premise Homeserver by re-running the installer on the host, then navigating to the Synapse section. Under Advanced, Config you will be presented with the homeservers' Public Key in a blue box.

Copy the entire string, taking the example above, it would be ed25519 jRheIX llomL0SL2eq6WfzaqtPX8QzYEP3c0a5E9G9NNamU4JQ. From this string, you can derive the Key ID and Public Key required when you wish to add this homeserver to anothers' Federation Trusted Key Servers.

  1. The Key ID is the first two sections joined with a :, so ed25519:jRheIX
  2. The Public Key is the remainder of the string, so llomL0SL2eq6WfzaqtPX8QzYEP3c0a5E9G9NNamU4JQ

Allow List

federation_domain_whitelist

Use the Allow List to restrict federation to the given whitelist of domains, if not specified, the default is to whitelist everything. Simply provide the homeservers' federated server name, i.e. the base domain of the homeservers' you with to federate with.

We recommend also firewalling your federation listener to limit inbound federation traffic as early as possible, rather than relying purely on this application-layer restriction.

This does not stop a server from joining rooms that servers not on the whitelist are in. As such, this option is really only useful to establish a "private federation", where a group of servers all whitelist each other and have the same whitelist.

Back to top