Native Federation Configuration

Prev Next

Native Federation is currently in Alpha and not recommended for production use. Expect breaking changes and limited functionality. Use in testing environments only.

This guide explains the federation settings and gives clear, actionable steps, recommended values, and security considerations for configuring federation between Matrix-protocol servers (federated workspaces). Use this to configure the Native Federation on your workspace and understand the implications of each field.

Prerequisites

  • Administrative access to your Rocket.Chat workspace.

  • A domain name you control for federation (e.g., acme.com).

  • Knowledge of your server’s network accessibility (ports, reverse proxy, TLS).

  • A secure location to store a private signing key (this key must remain confidential).

Quick start Native Federation (step-by-step)

  1. To access the Native Federation settings, go to Administration > Workspace > Settings > Federation.

  2. Toggle Enable native federation ON to allow inter-server communication using the Matrix protocol.

  3. Set Federated Domain to the domain you want the server to respond to (example: acme.com). Do not include http(s):// or any path after it.

  4. Choose a Signing Key Algorithm (example:ed25519). It controls the signature algorithm used for signing federation messages.

  5. Set Signing Key Version (a numeric version; 0 is common for the initial key). It allows rolling keys over in the future while preserving signature verification across versions.

  6. Paste the Signing Key (the server’s private key encoded as base64) into the field. Keep this private. It authenticates federation requests.

  7. Set Maximum number of members when joining a public room in a remote server (default: 100 )

  8. Optionally populate Domain Allow List to restrict which remote domains you will federate with. (Requires workspace restart.)

  9. Toggle Process Typing events ON/OFF depending on whether you want typing notifications exchanged.

  10. Toggle Process Presence events ON/OFF depending on whether you want presence (online/offline) synchronized across servers. (Enabling presence events may increase the load on your server and network traffic considerably, especially if you have many users. Only enable this option if you understand the implications and have the necessary resources to handle the additional load.)

  11. Toggle Allow joining encrypted federated rooms ON/OFF to enable or restrict joining end-to-end encrypted rooms on remote Matrix servers. (Messages in these rooms cannot be decrypted in Rocket.Chat. Use with caution.)

  12. Toggle Allow joining non-private rooms ON/OFF to control whether users can join public rooms on other federated servers. (It is recommended to keep this setting OFF while Native Federation is in Alpha.)

  13. Save and validate: Apply the configuration and validate by attempting federation operations (room join, message exchange) with a known remote Matrix server. Monitor logs for errors.

Troubleshooting checklist

  • DNS and reachability: Verify your federated domain resolves and is reachable over the required ports.

  • TLS errors: Confirm certificates are valid for the domain and CA trust chains are complete.

  • Discovery issues: If discovery fails, verify your configuration points to the correct host and port.

  • Signature verification failures: Check signing key, algorithm, and version consistency between published keys and configuration. Rotate and re-publish keys if necessary.

  • Room join failures: Confirm the configured maximum public-room member limit is not blocking joins. Check logs for rate-limiting or timeouts.

  • Excessive load: Disable typing/presence events and test again; scale resources if needed.

For issues beyond configuration and limitations, escalate at Github.