Rocket.Chat Matrix federation: when cross-organization chat needs it
Federation links separate servers so that each user keeps the identity of their home server, which lets partner staff join a shared room without an account on your workspace. The supplied facts describe Synapse federation, so whether and how Rocket.Chat workspaces federate with each other and with Matrix servers must be confirmed in the Rocket.Chat documentation for the version you run. Treat that check as the first gate, before any design work starts.
Federation fits when several external parties need ongoing shared rooms, such as a bank and its payment processors, a hospital network and its referral partners, or a supplier group and a regulator's reporting desk. The alternative is issuing guest accounts on your own workspace. Guest accounts keep identity inside your environment, but you then provision, review and remove every external person yourself. Federation moves that identity lifecycle to the partner's server, while you decide which servers you trust. Illustrative example: a procurement team with three suppliers and a few shared rooms may find guest accounts simpler, while a consortium with dozens of member organizations usually cannot manage that many accounts well.
On the Synapse side, the settings that shape a federated design are server_name, federation_domain_whitelist and delegation. The server_name value determines how users and rooms are identified, so decide it before anything is shared and confirm the consequences of changing it later. The federation_domain_whitelist setting restricts federation to listed domains, and an empty list disables federation entirely. Synapse uses port 8448 by default, and delegation can serve identities from another host on port 443. The Synapse documentation recommends firewalling the federation listener as well, so network policy is part of the review.
Operating a federated homeserver adds recurring work. Synapse recommends PostgreSQL for production, and its upgrade notes warn that rolling back can be difficult because of database schema changes between releases. Larger deployments scale with worker processes that rely on Redis for replication. Synapse is licensed under AGPL-3.0, with commercial licenses available from Element, and the project's 2023 move to AGPLv3 for future contributions is relevant if you modify the code or offer it to others. Ask legal counsel to confirm which license terms apply to your deployment model.
Before enabling anything, put four questions to your Rocket.Chat and Matrix vendors or partners: which federation protocols the workspace version supports, whether it federates with Matrix servers in both directions, which administrator controls limit federated rooms and users, and how federation interacts with end-to-end encryption and retention. Then run a security review covering allowed domains, listener exposure, identity provider trust and offboarding of partner users. Record the answers in the design, because they decide whether federation is a supported path or a custom build.
Federation options and when each fits
This table compares the federation choices a team makes before configuring Rocket.Chat Matrix federation: who can federate, how users are addressed, and which homeserver runs the protocol. Read each row for the condition that makes it fit and the operating commitment it creates. Settle the access policy and server_name first, because changing them later affects user identities and room addresses.
| Option | When it fits | What it commits the team to |
|---|---|---|
| Open federation with no allow list | The organization expects to exchange messages with many unknown servers and accepts wider exposure. | Ongoing abuse handling, a moderation policy for external rooms, and monitoring of the federation listener. |
| Allow list using federation_domain_whitelist | Collaboration partners are known and their domains are fixed for the project. | Keeping the list current as partners change, verifying partner domains, and firewalling the federation listener as Synapse recommends. |
| Federation disabled with an empty list | The workspace must stay internal for now, or federation is planned for a later phase. | No cross-organization rooms, while the homeserver still needs patching, backups and access control. Revisit the setting when needs change. |
| Delegation to a separate host | The public domain should stay on the main company name while the homeserver runs on its own host. | Well-known delegation records, DNS and TLS for the delegated host, and a fixed server_name chosen before any users join. |
| Serving federation on the main name | The team controls the server_name host directly and can open the federation port on it. | Opening port 8448 (the Synapse default), managing its TLS certificate, and exposing the listener on the main host. |
| Synapse homeserver | The team wants the most widely documented Matrix server, with Element as its upstream developer. | PostgreSQL 14 or newer and Python 3.10 or newer for current releases, AGPL-3.0 license review, and careful upgrades since rollback can be difficult. |
| Other Matrix implementations (Dendrite, Conduit forks) | The team has a specific runtime or resource reason to evaluate an alternative server. | Confirming federation support with Rocket.Chat and the implementation's maintainers, separate testing, and no documented Synapse path to fall back on. |
Which homeserver and license to plan around for federation
Choose the homeserver and its license before any Rocket.Chat federation work starts. The server you run determines which federation behavior you inherit, how often you must upgrade, and which legal terms apply to your organization. Matrix.org maintains a list of homeserver implementations, and they differ in language, license and maturity. Synapse is the most widely documented of them, is written in Python and is developed by Element. Dendrite is also developed by Element, while Conduit and its Rust forks are licensed under Apache-2.0. Ask Rocket.Chat which homeserver implementations its federation support has been tested against, because a server listed on Matrix.org does not guarantee compatibility with your workspace.
Synapse is distributed under AGPL-3.0, and Element also offers commercial licenses for Synapse, according to the Synapse documentation. On December 13, 2023, Element announced that future contributions to Synapse would be licensed under AGPLv3 rather than Apache 2.0, moved the repositories from the matrix-org organization to element-hq on GitHub, and began selling AGPL exceptions. Contributors now sign a contributor license agreement. Record the exact license, repository and release channel you based your plan on, because older guides, forks and packaging may still point to the previous locations and terms.
The AGPL-3.0 license includes obligations that apply when software is modified and offered to users over a network. Whether those obligations reach your organization's internal use, and whether your patches, custom connectors or bridge code create source-availability duties, is a question for your legal team to review before you deploy. The same review should cover whether Element's commercial terms suit your use and what they cost, since those terms are negotiated directly with Element. Do not treat this section as legal advice. Bring the license text, your planned modifications and your intended user base to counsel early so that the answer shapes the architecture rather than arriving after go-live.
The current Synapse release on the GitHub releases page is v1.163.0, published October 14, 2026. Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer, so confirm both versions in your environment before you pick a release. Synapse drops support for Python and PostgreSQL versions once they reach upstream end of life, and its upgrade notes warn that rolling back can be difficult because schema changes occur between releases. Pin a tested version, rehearse each upgrade in staging, and take a verified database backup before every production change.
Setup sequence for a federation pilot with one partner domain
This sequence takes a Synapse homeserver from naming plan to a tested federation with one partner domain. Each step ends with a check, so the pilot stays limited to that domain and the team can show that both servers accept each other's signed traffic. Confirm with the Rocket.Chat documentation for your version how its workspace connects to the Matrix side before you start.
Agree the server_name and domain plan
Your team and the partner's team agree in writing on the server_name, the hostname that will serve federation traffic, and the partner domain that will be whitelisted. The server_name fixes how user IDs and room IDs are formed, so changing it after accounts exist affects identifiers, and you should confirm the consequences in the Synapse configuration manual before you commit. Done means both teams have signed off on a single document listing these values. Check: each name in the document resolves to the intended server when queried from outside your network.
Set delegation and DNS records
Decide whether federation will be served directly on port 8448 or delegated so that user IDs such as @user:your-domain are served from another host on port 443. Your DNS team creates the matching records and the TLS certificate covers the federation hostname. Synapse federation documentation describes both patterns, and the choice should match what the partner can reach. Check: the Matrix federation tester reports the expected host, port and certificate for your domain with no resolution or certificate errors.
Restrict the federation listener with firewall rules
Place the federation listener behind firewall rules that the Synapse documentation recommends, allowing inbound traffic only from the partner's published address ranges on the federation port. Your network team exchanges those addresses with the partner and records the rules as code or change tickets. Keep client traffic on its own listener so the federation rule does not affect users. Check: a connection attempt from an address outside the partner's ranges is refused, and a connection from the partner's range reaches the listener.
Set federation_domain_whitelist to the partner domain
Add only the partner domain to federation_domain_whitelist in the homeserver configuration. An empty list disables federation, so confirm the list contains exactly one entry before restarting. Make the change in the same configuration management process your team uses for other homeserver settings. Check: after restart, a test account on a domain that is not on the list cannot start a federated conversation with a local user, and the server log records the refusal. Also confirm that the partner domain is accepted.
Configure upstream SSO if your pilot uses it
If the pilot authenticates users through an identity provider, configure Synapse for the chosen method, such as OpenID Connect through oidc_providers, SAML2 through saml2_config, or CAS, according to the configuration manual. Register the callback URLs with the identity provider using the server_name and hostname from step one. Skip this step only when the pilot uses local accounts, and record that decision in the plan. Check: a pilot user signs in through the identity provider, and a user that the provider does not know cannot create an account.
Verify keys and test one room end to end
Ask the partner to query your server's signing keys and confirm that the keys they receive match the ones on your server. Then create one test room, invite one test user from the partner domain, and exchange messages in both directions. Your team and the partner keep a short written log of the room ID, the test steps and any errors. Done means messages arrive on both sides and both servers show the same room membership. Check: the federation tester shows no key or signature errors, and the partner's server reports the same room ID.
Security review federation needs before the listener opens
Federation extends your workspace trust to other servers, so each item below needs a named decision and an owner before the listener accepts traffic. The cards cover who can connect, how that access is restricted and recorded, how remote identities and room data are handled, and who signs off on each partner.
Allow list scope and change control
The allow list determines which domains can exchange events with your server. In Synapse, the federation_domain_whitelist setting restricts federation to listed domains, and an empty list disables federation. Decide whether the list is per partner or per region, and who may change it. Each addition should go through a documented change with a reason, an expiry date and a rollback step. Confirm with your Rocket.Chat deployment how its federation settings map to the homeserver configuration.
Firewalling the federation listener
Synapse federates on port 8448 by default, and delegation can serve user IDs from another host on port 443. The Synapse documentation recommends firewalling the federation listener in addition to the allow list. Confirm which ports, hostnames and paths your chosen design exposes, and whether inbound traffic can be limited to the addresses of approved partners. Test that blocked servers cannot reach the listener, and that the reverse proxy does not expose internal endpoints.
Identity provider and remote account lifecycle
Remote users keep their identity on their home server, so your identity provider does not control their accounts. Decide which of your users may be federated, how they authenticate on your side, and whether any remote accounts are provisioned locally. Your offboarding process must cover federated access, not only local accounts. Synapse supports OpenID Connect, SAML2 and CAS for its own sign-in, and Rocket.Chat plans list LDAP, Active Directory and SSO. Confirm how each of these applies to federated users.
Retention and export of federated rooms
Every participating server stores its copy of the events in a shared room, so retention on your side does not delete the copies held by a partner. Define the retention period for federated rooms, how legal holds apply, and how exports are produced and access-controlled. Check whether Rocket.Chat retention settings apply to federated content, and whether the Matrix homeserver stores events on the same schedule. Ask each partner to confirm its retention practice in writing.
Logging of cross-server traffic
Cross-server activity needs logs that show which remote server sent which request, when, and for which room. Those records should be retained on a schedule your investigators can use and protected from change. Correlate homeserver logs with the allow list and firewall logs so that a blocked or unexpected server is visible. Rocket.Chat paid plans list tamper-evident audit trails for messages, files and sessions. Confirm whether that coverage includes federated events before relying on it.
Approval owner for each partner
Each partner domain should have a named business owner, a security approver and a written record of the approval. The approval should state the purpose, the rooms or users in scope and the date of the next review. Schedule periodic reviews that remove partners who no longer need access. Include the steps for suspending a partner quickly during an incident. Ask your implementation partner to set up these records as part of the handover, so they stay current after go-live.
Scaling and upgrades once partners depend on the federation
Synapse scales through worker processes, so the scaling plan has to exist before partners start sending federation traffic. The main process and all workers connect to Redis, which relays replication between processes. The generic worker handles client, federation and event traffic, which makes a single generic worker the simplest layout to start with. Before adding workers or moving traffic types onto dedicated workers, confirm the layout against the Synapse workers documentation for the version the pilot runs. Each added process also holds a connection to Redis, so capacity planning must cover Redis as well as the homeserver.
Redis becomes a shared dependency for the whole homeserver. If it fails or slows down, replication between the main process and its workers suffers, so it needs its own monitoring, alerting and failover design, plus a named owner. Ask the platform team who operates it, whether it runs in a highly available configuration, and how it is backed up. Then load test the layout with traffic that resembles what partners will send, including federation requests from the partner's server and not only internal users. The results show which process is the bottleneck and therefore where the next worker belongs. Record the layout in the runbook so the on-call engineer can see which processes serve which traffic.
Rollback is the hardest part of Synapse operations to plan for. The upgrade notes warn that rolling back can be difficult because of database schema changes between releases, so treat each Synapse upgrade as a change that may not reverse cleanly. Before any upgrade, take a PostgreSQL backup, restore it into a separate environment and run the new version against that copy. Synapse recommends PostgreSQL for production. Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer. Synapse also drops support for Python and PostgreSQL versions once they reach upstream end of life, so those prerequisites belong on the upgrade calendar alongside the Synapse version itself.
Rocket.Chat adds a second clock to the pilot. Standard releases are supported for 6 months and LTS releases for 12 months. After end of life, a version gets no security or bug fixes, cloud services such as the push notification gateway stop working, and unsupported versions may lose the ability to connect with the official mobile and desktop clients. Both servers in the pilot therefore need an upgrade calendar agreed with partners before go-live. Record each server's current release line and its end-of-life date from the version durability documentation, the upgrade windows, the notice partners need, and the freeze dates around their busy periods. The Synapse releases page lists v1.163.0, published October 14, 2026, so the calendar should name the exact version each side targets.
What do buyers ask before federating Rocket.Chat with partners?
How much does Rocket.Chat Matrix federation cost to implement?
Cost follows the written scope, and DeployOpen does not publish a price list. The main drivers are the number of partner domains, the identity design, the depth of the security review and whether a second server is needed. Separate licensing from implementation. Rocket.Chat's Commercial, Government and Defense plans are priced by quote, and multi-instance or microservice designs require a paid plan. Ask the quote to split one-time work (design, configuration, testing, cutover) from recurring items (licensing, upgrades, monitoring, support retainers). Also ask whether the Matrix homeserver, its database and its hosting are included or billed separately.
How long does a Rocket.Chat federation project take?
Duration depends on the same drivers as cost, and no duration figure applies to every design. A single partner on an existing identity provider is a much smaller job than several partner domains with separate trust reviews. Partner availability often sets the pace, because each federation pair needs joint testing and a change window on both sides. Request a timeline with milestones in the written scope, and ask which steps depend on your partners or your identity team.
How many partner domains can one federation design support?
Each partner domain adds configuration, DNS and trust work, so the count matters more than the software. Synapse's federation_domain_whitelist setting limits federation to listed domains, and an empty list disables federation. Every added domain needs an entry, a test and a review of what that partner can see. The Synapse documentation also recommends firewalling the federation listener, which defaults to port 8448, so each partner added means a network change to plan. Ask your provider how the allowlist will be governed and who approves each new domain.
What does our team need to provide for a federation project?
Expect to provide DNS control, certificates, firewall changes, identity administration and named owners. Your team must control the DNS records that federation depends on, including delegation if user IDs are served from another host on port 443. You will need TLS certificates for each server name, change windows on your firewalls and administrator access to your identity provider. Name one owner for security review decisions and one contact for each partner. Ask for this list in writing before the scope is signed, so gaps appear before the work starts.
Can our internal team run Rocket.Chat federation without an implementation partner?
Yes, if your team already runs the components involved, but the skills must cover more than Rocket.Chat. Rocket.Chat 8.x requires MongoDB 8.0 or later as a replica set. A Matrix homeserver such as Synapse also needs its own database, which the Synapse documentation recommends as PostgreSQL in production, and recent Synapse releases require PostgreSQL 14 or newer and Python 3.10 or newer. Federation also needs DNS, TLS and firewall work, plus a security review. Assess each skill honestly, and ask a partner to quote the parts your team cannot cover in-house.
Does federation require a second server or a separate homeserver?
It depends on the design and the version, so confirm it against Rocket.Chat's current documentation before you commit. Rocket.Chat's reference architectures suggest one instance with a MongoDB replica set for up to 500 concurrent users, with multiple load-balanced instances linked by NATS above that size, which requires a paid plan. Matrix federation also depends on a homeserver with its own server name, and Synapse scales with worker processes that use Redis for replication. Ask the provider to state in the scope which servers are new, which are shared, and what each one needs to run.
How do identity and single sign-on affect federated users?
Identity design decides how users appear across organizations, so settle it before configuration. Synapse supports single sign-on through OpenID Connect, SAML2 and CAS, and its server_name setting fixes how users and rooms are identified. Rocket.Chat's Starter plan includes LDAP, Active Directory and single sign-on, while its paid plans add SAML and LDAP user group mapping. Decide which identity provider authenticates each organization, how accounts are provisioned and removed, and whether partner users need access at all.
How often must a federated Rocket.Chat server be upgraded?
Plan for regular upgrades, because each supported line has an end of life date. Rocket.Chat standard releases are supported for 6 months and LTS releases for 12 months. After end of life, a version gets no security or bug fixes, cloud services stop working, and Rocket.Chat says the official mobile and desktop clients may lose their connection. Synapse also drops support for Python and PostgreSQL versions once upstream support ends, and its upgrade notes warn that rolling back can be difficult because of schema changes. Ask for an upgrade calendar that covers both servers and every partner.
How DeployOpen works on this
DeployOpen plans and builds Rocket.Chat Matrix federation as a scoped engagement in infrastructure you control. Before work starts, the scope is written down, including which Matrix homeserver, identity setup and federation partners are involved. Engagements are fixed-scope, and ongoing support is available as a retainer for the platform.
How we scope
- The written scope names each federation partner, its server_name and the domains allowed to federate.
- It records which rooms, users and bridges cross the boundary, and which stay internal to each organization.
- It states the Rocket.Chat and Matrix versions, the database layout and the hosting targets in scope.
How we build
- The chosen Matrix homeserver is deployed with PostgreSQL, with workers and Redis sized for expected traffic.
- Delegation or port 8448 federation is configured, with the federation listener firewalled to approved domains only.
- Rocket.Chat is connected to identity through the SSO, LDAP or SAML options your plan supports.
How we hand over
- Handover includes the written configuration, the federation allow list and a record of each partner's test results.
- Runbooks cover upgrades, Synapse rollback limits, schema changes and removing a federation partner.
- Operators receive the security review findings for federation, with open items and owners listed.
How we support
- Retainers can cover Rocket.Chat and Synapse upgrades, since unsupported versions stop receiving fixes.
- Support can include monitoring of federation traffic, dependency tracking and periodic partner allow list reviews.
- Ask whether the quote includes security testing of the federation endpoints as a separate scoped item.
