Matrix federation policy: deciding who your users can reach
An organization running or planning a self-hosted Matrix homeserver has to decide which other servers its users can exchange messages with. The options are open federation with the wider Matrix network, federation limited to a list of partner domains, or no federation at all. This decision sets how room data moves between your infrastructure and other servers, how users and rooms are named, and which network paths your firewall must allow. It is harder than flipping one setting because those three areas depend on each other, and changing the choice later can affect existing rooms, accounts and network rules. In Synapse, the most widely documented homeserver, the main controls are the federation_domain_whitelist setting and the server_name setting. An empty whitelist disables federation entirely. A list of domains restricts federation to those domains. Leaving the whitelist unset allows federation with any server that responds on the federation listener. The server_name setting fixes how user IDs such as @user:example.com and room identifiers are written, so it should be chosen with care before any accounts exist. Your policy therefore has to be settled at the naming stage, not after launch. The network side is equally important. Synapse federates on port 8448 by default, and delegation lets the domain in user IDs be served from another host on port 443. Each path you choose changes what must be reachable, from where, and through which load balancer or reverse proxy. The Synapse configuration manual recommends firewalling the federation listener as well as setting the whitelist, so the application setting and the network rule should match. Confirm with your network team which ports and hosts they can open, and test the chosen behavior from outside your network before go-live. For each option, write down the decision owner, the business reason, and the partner domains if any. Ask the team to confirm whether any partner organization runs its own homeserver, which server_name it uses, and whether it will accept your delegation setup. Confirm also whether your policy must be documented for a compliance assessment, since auditors will look for a written and enforced rule rather than a default. Revisit the list when partners change, because a whitelist that is never reviewed becomes an unexamined data path. Before you choose, check how each option interacts with identity and bridges. Users in a closed federation still need accounts, which affects the identity integration work covered elsewhere on this page. Bridges to other chat platforms send traffic through your homeserver and may be a reason to limit federation, or a reason to permit specific partner domains. Treat the federation decision as a design input for the rest of the deployment, and record the rationale so that the next person who reviews it understands the data control trade-off you accepted.
Components and settings behind federation policy
Federation policy in Synapse is set by a small group of components that work together: the server name, the federation listener, the public name resolution path, the allowlist, the firewall, and the reverse proxy. Each one can silently widen or narrow who can exchange data with your homeserver, so they should be reviewed as one decision rather than separately. The same settings apply whether Synapse runs as a single process or with workers.
The server_name setting
The server_name value sets the domain that appears in every user ID and room ID on your homeserver, such as @user:example.com. It is fixed once users and rooms exist, so changing it later is effectively a migration. Decide it before deployment, confirm the domain is one your organization controls long term, and make sure it matches the name clients and other servers will use to find you.
The federation listener on port 8448
Synapse serves federation traffic on port 8448 by default, and this listener is where other homeservers connect to exchange events. Check whether the listener is enabled in your configuration, which network interfaces it binds to, and whether TLS terminates on it correctly. If your policy is closed or partner-only, this listener is the surface that the allowlist and firewall rules must govern.
Delegation through a well-known file on port 443
Delegation lets the server name example.com serve identities while the actual homeserver runs on a different host, reached through a well-known file served over HTTPS on port 443. This avoids opening port 8448 publicly in many setups, but it also means the well-known file is a public statement of where your server lives. Confirm the file content, the TLS certificate on the delegated host, and that the target answers on the expected port.
The federation_domain_whitelist setting
The federation_domain_whitelist setting limits federation to the domains you list. An empty list disables federation entirely, which suits single-organization deployments, while a populated list supports a partner-domain model. Maintain the list as a reviewed change, since every addition expands the set of servers that can send events to your users and rooms.
Firewall rules for the federation listener
The Synapse documentation recommends firewalling the federation listener in addition to the allowlist, so that an application-level setting is not the only control. Define which source addresses may reach the federation port, and in a partner model, whether those addresses can be kept current. Test from outside the network after every change, because a rule that blocks legitimate partners fails quietly.
The reverse proxy in front of Synapse
A reverse proxy usually terminates TLS and forwards client, federation and well-known traffic to Synapse, and misconfiguration here is a common cause of federation failures or unintended exposure. Check which paths and ports the proxy forwards, the headers it passes to Synapse, the maximum request sizes, and whether admin endpoints are reachable from outside. Record the proxy configuration alongside the Synapse configuration so both are reviewed together.
Open, partner-only or closed: which federation policy fits
This table compares three Synapse federation settings: open federation, a federation_domain_whitelist of partner domains, and an empty list that disables federation. Read each row across to see when the option fits, what it means for data leaving your organization, what users can reach, and the upkeep it creates. The main takeaway is that the narrower the policy, the more data stays inside your boundary, and the more ongoing list management you take on.
| Consideration | Open federation | Partner-only whitelist | No federation (empty list) |
|---|---|---|---|
| When it fits | Public or community-facing rooms where people on other servers must join and talk freely | Organizations with a defined set of partners such as suppliers, regulators or affiliates that need shared rooms | Internal-only deployments where confidentiality requirements rule out any external room traffic |
| Data leaving the organization | Room events and membership data can be replicated to any reachable homeserver that joins a room | Replication is limited to listed domains, but those partner servers hold copies of shared room data | No room data is sent to other servers through federation |
| What users can reach | Users can join and message rooms hosted on most other Matrix servers | Users can reach rooms on listed partner servers only | Users can reach only accounts and rooms on the local server |
| Ongoing operational work | Monitoring abuse, managing server-level blocks and reviewing moderation load | Maintaining the partner list, verifying domain names and reviewing the list when partners change | Little federation upkeep, but users may later ask for external access and the policy must be revisited |
| Network controls to confirm | Federation listener must be reachable from the internet on the agreed port | Recommended to firewall the federation listener so only expected partner hosts can connect | Firewall the federation listener so no external host can reach it |
| Change effort later | Low to open, but closing it later affects existing shared rooms | Adding a partner is a configuration change and restart, and removing one should be checked against rooms that depend on it | Opening later requires a policy decision, DNS and port planning, and user communication |
| Key question to confirm with the vendor or your environment | Which abuse and moderation tools your chosen homeserver and clients provide | Who owns the partner list, how partner domains are verified, and how removals are communicated | Whether any bridge or integration depends on federation before the policy is set |
How to configure federation on a Synapse homeserver
This sequence takes a Synapse homeserver from a chosen federation policy to a tested configuration. Each step names the setting or network change involved and the check that closes it. Following the order matters because the server name is hard to change once users exist.
Fix the server name before creating users
Set server_name in homeserver.yaml before the first account exists. This value becomes part of every user ID and room ID, and changing it after users exist affects their identities, so it is hard to undo cleanly. The platform engineer confirms the name matches the domain users will see, and checks that the setting is in place before the first registration. Done when a test user ID shows the intended domain.
Decide the federation policy
Choose one of three postures: open federation with any server, federation limited to a named set of partner domains, or no federation at all. Each choice sets who can receive and send room data outside your organization, which matters for confidentiality and for how much control you keep over where messages travel. Security, legal and the teams that will chat with outsiders should sign off in writing. The step is complete when the chosen posture and the list of partner domains, if any, are recorded in the design document.
Set the whitelist or disable federation
Edit federation_domain_whitelist in homeserver.yaml. Listing domains restricts federation to those servers, and an empty list disables federation entirely. Keep the list in version control so changes go through review. Before restart, the engineer checks that the file loads without syntax errors and that the list matches the approved decision. The step is done when the values in the file match the policy from the previous step.
Publish delegation or serve port 8448
Choose how other servers find yours. Synapse federates on port 8448 by default. Delegation lets user IDs such as @user:example.com be served from another host on port 443, so the public name stays on the standard HTTPS port. Your DNS team publishes the delegation file or DNS record, and the platform engineer confirms it resolves. Done when a lookup of the server name returns the expected host and port.
Configure the reverse proxy and firewall
Route the federation listener through the reverse proxy, and restrict direct access to it. Only the federation listener needs to be reachable from other servers, while client, admin and internal listeners stay on private networks. Synapse's documentation recommends firewalling the federation listener, so the network team writes rules that allow the approved source addresses where your policy requires it and block the rest. Done when an external scan shows only the intended ports open.
Restart Synapse and test federation
Restart the homeserver so the new settings load, then check the logs for configuration errors. Test from outside your network with a federation checker that resolves your server name and reports the port and certificate it finds. Then ask a partner domain on the list to join a test room, and confirm that a domain not on the list is refused. Done when the approved partner works, an unlisted domain is refused, and the results are written into the change record.
What drives federation effort and how to keep it down
This table lists the factors that change how much work federation takes on a Synapse deployment, and the practice that keeps each one under control. Read each row as a question to answer before scoping, since the answers decide whether federation is a one-time setup or a recurring task. The main takeaway is that most of the effort comes from frequent partner changes and unclear DNS and certificate ownership, so both should be settled early.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Number of partner domains | Each allowed domain adds an entry to the federation allow list, testing, and a contact to maintain. The list must match what the homeserver actually permits. | Limit the list to named partners, record the business reason for each, and review it on a fixed schedule. |
| How often partners change | Each new partner, renamed domain or retired server means a configuration edit, a restart and a check that delegation still resolves. | Use a written partner change process with a request form, a named approver and a single change window for list updates. |
| Existing DNS and certificate control | If the team cannot edit records or issue certificates for the server name, every federation change waits on another group. | Confirm who owns the zone and certificate issuance before design. Agree how delegation records and certificate renewals are requested and tracked. |
| Single delegation host | Delegation can point each user domain at a separate host, so every extra host adds certificates, records and monitoring. | Serve delegation from one well-known host under the main domain, and keep the federation endpoint behind a single managed name. |
| Whether ports 443 and 8448 can be opened | Synapse federates on port 8448 by default. If only 443 is open, delegation must point federation traffic at a reachable host, which needs testing. | Confirm early with network and firewall owners which ports are allowed inbound. Test federation from outside the network before go-live. |
| Network segmentation | Federation listeners often sit in a separate zone from clients, and each firewall rule or proxy path must be approved and documented. | Map traffic flows once, keep the federation listener behind a reverse proxy, and firewall the listener to permitted peers only. |
| Number of environments | Test, staging and production each need their own server names, allow lists and certificates, so settings drift between them is a common fault. | Keep allow list and delegation settings in version-controlled templates and promote them unchanged between environments. |
| Policy documentation for auditors | Assessors will ask who may federate, how partners are approved and how changes are logged. Missing evidence turns a configuration task into a rework task. | Keep a short federation policy, the approved partner register, and change records together, and review them at each audit cycle. Note that DeployOpen prepares evidence but does not issue audit opinions. |
Federation setup by hosting model
A single-node Synapse deployment runs the main process on one host, and that host answers client and federation requests directly. Federation is configured in the homeserver configuration file, and the listener that serves it is usually exposed on the default federation port, 8448, unless delegation moves it to port 443. This is the simplest layout to reason about because there is one place to check the listener, the firewall rules and the server_name setting.
Points to confirm for a single node:
- The server_name value, which fixes how user IDs and room IDs are written and cannot be changed casually after users exist.
- Whether federation listens on port 8448 directly or is reached through delegation on port 443.
- Whether federation_domain_whitelist is set to a partner list, left unset, or set to an empty list to disable federation.
- Which firewall rules admit inbound federation traffic and which block it, including the federation listener itself.
- Who owns the TLS certificate for the federation endpoint and how renewal is monitored.
Before go-live, confirm that the federation listener answers only on the intended interfaces and that the server is reachable from the partner domains you intend to allow. Ask your implementation partner to show the resolved configuration values, not only the files that set them.
A worker-based deployment splits Synapse into the main process and additional worker processes, with Redis relaying replication between them. In this model, the generic worker handles client, federation and event traffic, so the load balancer must route federation requests to a generic worker rather than the main process. Port and delegation settings still apply, but they now sit in front of the load balancer, which makes routing rules a second place where federation can break.
Points to confirm for a worker-based deployment:
- Which worker instances receive federation endpoints, and that the load balancer routes those paths to them.
- That the federation listener is not reachable through paths that should stay internal, such as admin endpoints.
- How Redis is deployed and secured, since it carries replication between all processes.
- That delegation records and the TLS certificate match what the load balancer presents on port 443 or 8448.
- Whether the federation_domain_whitelist and firewall settings are applied on every worker host, not only the main process.
Test federation after every change to the load balancer or worker layout. Synapse documentation describes the worker model, and your team should confirm the exact routing table against the release it runs, since it changes between versions.
On Kubernetes, the deployment usually places federation settings in the Helm values and in the ingress definition, and the cluster ingress controller carries most of the port and TLS handling. The homeserver configuration, the ingress host names and the delegation records have to agree with each other. A mismatch often appears only after the pods restart or the ingress is changed, so it is easy to miss during initial testing.
Points to confirm for a Kubernetes deployment:
- The Helm values that set server_name, the federation domain whitelist and the listener configuration.
- The ingress rules that expose the federation endpoints, including whether port 8448 is published or only port 443 is used through delegation.
- The TLS secret referenced by the ingress and the process that renews it.
- Network policies that limit which namespaces and pods can reach the federation listener.
- Whether the delegation record for server_name points at the host that the ingress actually serves.
After each Helm upgrade, check the rendered configuration and the ingress object, not only the release status. Confirm the exact chart version and values schema with the vendor or chart maintainers, because option names and defaults can change between releases.
An air-gapped Matrix installation is closed by design. With no route to the public internet, the homeserver cannot send or receive federation traffic, so it operates as an isolated Matrix network. Federation settings are still worth configuring deliberately, because the server_name and any internal delegation records determine how identities are written and how internal hosts resolve each other. Treat the lack of outbound federation as a property of the network, and verify it rather than assuming it.
Points to confirm for an air-gapped installation:
- That no egress route to other homeservers exists, checked from the homeserver host and from the workers and Redis hosts.
- That federation_domain_whitelist is set to an empty list or the federation listener is disabled, so the configuration states the intent.
- How clients resolve the server name inside the network, through internal DNS or a local delegation record.
- How software packages, container images and updates reach the environment, since they must come through an approved transfer path.
- Whether any bridges or integrations also have no external reach, because they can open routes that federation controls do not cover.
Record the closed state as part of the configuration baseline so auditors and your own team can see it. Ask your implementation partner to show the network evidence that supports the claim, not only the configuration file.
Securing the federation listener and naming
Federation is where a Matrix homeserver talks to the outside world, so the listener, the published server name and the admin surface need to be controlled together. The cards below cover the boundary controls to decide and verify before any remote server can reach your homeserver.
Firewalling the federation listener
Synapse's documentation recommends firewalling the federation listener in addition to any allowlist setting, so that only the servers you intend to federate with can open connections to it. Confirm which port and interface the listener binds to in your configuration, and test the rule from an address outside your allowed set. Record the rule in your change log so a later firewall or load balancer change does not reopen the port silently.
Federation domain allowlist
The federation_domain_whitelist setting restricts federation to listed domains, and an empty list disables federation entirely. Decide which of the three postures you need, open, partner-only or closed, and write the resulting list down as a controlled document. Review the list whenever a partner domain changes, because a stale entry keeps a retired partner connected.
Control of delegation records
Delegation lets user IDs on your domain be served from another host on port 443, so whoever can publish or change those DNS or well-known records can redirect where your users' traffic goes. Restrict write access to the zone that holds them, require change review, and monitor for edits. Confirm with your DNS provider how access is logged and who holds account-level permissions.
Server name and port choices
The server_name value fixes how user IDs and room IDs are written, so changing it later is effectively a new identity. Decide between serving federation on port 8448 directly or using delegation to serve it on port 443, and check that your certificate, DNS and firewall rules match that choice. Confirm both paths with a remote federation tester before you announce the domain.
Certificate management for the federation name
Remote servers validate the certificate presented for the name your homeserver claims, so an expired or mismatched certificate breaks federation without an obvious client-side error. Assign an owner for issuance and renewal, automate renewal where your certificate authority allows it, and set alerts well before expiry. Confirm which names the certificate must cover, including any delegated host.
Keeping the admin API off federation
The Synapse admin API is powerful and should never be reachable from the federation listener or the public internet. Bind it to an internal interface or restrict it to administrator networks, and confirm with a test from outside that the admin paths do not respond on the federated endpoints. Review this configuration after every upgrade, since listener layout and reverse proxy rules can change between releases.
How to test that federation behaves as your policy says
A federation policy is only as good as the evidence that it works. Before you call the configuration finished, test it from inside your network and from outside it, and record the results against the policy you wrote. The checks should answer four questions: does delegation resolve to the federation endpoint you intended, can a listed partner domain exchange messages with your server, is a non-listed domain refused, and can the federation listener be reached from networks that policy says should be blocked. Each of these can fail independently. A correct federation_domain_whitelist setting does nothing if the listener is reachable from the internet, and an open firewall rule does nothing if delegation points somewhere unexpected.
Start with name resolution. Confirm that the well-known delegation for your server_name returns the host and port you configured, and that the federation port your clients and remote servers use answers with a valid certificate for that name. Synapse federates on port 8448 by default, and delegation lets user IDs such as @user:example.com be served from another host on port 443. Check both paths, because a stale DNS record or a reverse proxy rule can send remote servers to an address that no longer matches the config. Run the same checks from a host outside your network, since internal DNS often hides mistakes that remote servers will hit immediately.
Next, test the partner and refusal cases with real accounts on each side. Create a test room on your server, invite a user on a listed partner domain, and confirm that messages and membership events flow both ways. Then attempt the same from an account on a domain that is not on the list. The refusal should be visible: the remote server should not be able to join or send, and your logs should show the request was rejected. Ask your partner to run the same test from their side, because a successful send in one direction does not prove the list is enforced in the other. Keep the room IDs, timestamps and log lines as evidence.
Test the network boundary separately from the application. From a network that policy disallows, attempt to open a connection to the federation listener and to the reverse proxy that fronts it. The connection should time out or be refused at the firewall or load balancer, not reach Synapse. Repeat the test from an allowed partner network if you can reach one, to confirm the allow rule is as narrow as intended. The Synapse configuration manual recommends firewalling the federation listener in addition to the list, so treat the two controls as separate tests with separate evidence.
Finally, test failure in the safe direction. Set federation_domain_whitelist to an empty list, which disables federation, apply the change, and restart the homeserver. Then confirm that no federation traffic is sent or accepted: check that remote servers receive errors or no response, that the federation listener does not accept requests from partner networks, and that existing rooms with remote members stop receiving new events. A restart is part of the test because some changes take effect only after one. Record the time of the change, the restart and each check, and repeat the sequence after every configuration change, upgrade or infrastructure move. Confirm with your security team which evidence they need to retain and for how long.
Operating federation policy after go-live
This table sets out what to monitor, back up, review and document once federation is running, with the reason each item matters for data control. Read each row as an ongoing task with an owner, and confirm the exact log messages, metrics and certificate tooling against your chosen homeserver's documentation and your own environment. The main takeaway is that federation policy drifts unless someone checks it on a schedule, especially after upgrades and partner changes.
| Area | What to do | Why it matters for federation |
|---|---|---|
| Federation errors and refused requests | Review federation send and receive errors and requests refused by the federation whitelist or listener on a regular schedule. Confirm which log lines and metrics your homeserver exposes. | Refused or failing requests can mean a partner moved hosts, a certificate broke, or a blocked domain is still trying to reach you. Silent failures can hide a policy gap. |
| Certificate expiry for the federation name | Track expiry dates for the certificate serving the federation name and any delegation target, with alerts well before expiry. Confirm the renewal process and who receives the alert. | Remote servers reject connections when the certificate is invalid or expired, which can cut off a partner without any visible change on your side. |
| Configuration and signing keys backup | Back up the homeserver configuration, the signing key and the server_name settings in encrypted storage, with restore steps tested on a separate host. Confirm the exact key file locations for your implementation. | The signing key identifies your server to others. Losing it or changing it without a plan can break trust with existing federated rooms and partners. |
| Partner list review | Revisit the federation allowlist on a fixed schedule and when a partner leaves, changes domain, or a new business need appears. Record the approver and the reason for each change. | Allowlists age. Domains change owners, and unused partners remain trusted data channels unless someone removes them. |
| Upgrade impact on federation settings | After each upgrade, re-check federation-related settings, listener and port configuration (8448 or delegated 443), and the whitelist. Test with a known partner before declaring success. | Release notes can change defaults or require new configuration. Rolling back may be hard after schema changes, so verify federation in a staging copy first. |
| Evidence for the security and compliance owner | Keep a dated record of the federation mode, approved partners, configuration changes, review outcomes, monitoring alerts and key-handling events. Store it where the compliance owner can access it. | Assessors and internal risk reviews will ask who can exchange data with your users and how that decision is controlled. Documentation proves the policy is operated, not just written. |
Federation questions buyers ask before hiring help
What drives the cost of hiring help for Matrix federation setup?
Cost follows the written scope, and the main drivers are the number of partner domains, the number of environments and how much of the surrounding infrastructure needs change. Work typically includes federation policy design, server name and delegation decisions, DNS records, TLS certificates, reverse proxy and firewall changes, testing against a remote server, documentation and handover. Setup work is one-time. Certificate renewal, monitoring and any upgrade or support retainer recur. Costs rise when the DNS zone is hard to change, when change control takes long approval cycles, or when SSO or bridges are added to the same project. Ask for a quote with separate line items for design, configuration, testing, documentation and any recurring support, and confirm which of your own staff time is assumed in the estimate.
How long does it take to configure federation on Synapse?
The configuration itself is usually the shortest part, and the calendar time depends mostly on approvals and external dependencies. Confirm these with your team before agreeing a timeline: how long DNS changes take to approve and propagate, how long certificate issuance takes for the names you choose, the firewall change window, and whether a test homeserver exists where federation can be tried safely. Ask the implementation partner to state the sequence and which steps wait on your side. A written timeline should name the dependencies and the owner of each, so that a delayed firewall ticket does not get confused with a delay in the Synapse work.
What does our internal team need to provide for federation?
Your team provides access, approvals and named owners for DNS, certificates, the network path and the change process. On the DNS side, someone with zone edit rights must create the records for the server name or the delegation target. Certificates must cover the names that remote servers will connect to, so a certificate authority or internal PKI owner needs to be involved. The federation listener, usually on port 8448, or port 443 when delegation is used, needs firewall or reverse proxy rules, and these normally go through change control with a security reviewer. Illustrative example: a bank's network team approves one inbound rule for a single partner list, while the security team reviews the logging. Confirm these owners before the work begins.
Can one administrator set up Matrix federation alone?
One capable administrator can do the Synapse work alone, but the change process usually makes that person dependent on other teams. A single engineer with Synapse, PostgreSQL and reverse proxy experience can edit the homeserver configuration, test with a remote server and document the result. Setting up DNS, certificates and firewall rules often needs other people who hold those rights and sign-off. Two risks are worth weighing: knowledge concentrated in one person, and the lack of a second person who can respond when federation misbehaves. Whether one person is enough depends on your existing access, your approval rules and whether you also need coverage for upgrades and incidents. Confirm this with your own team before deciding.
What changes if we turn on federation after the launch?
Turning federation on later changes your exposure, your moderation load and possibly your identifiers, so the decision is easier to make before users join. Once federation is on, remote servers can reach the federation listener and users can share rooms with outside people. That affects who can see message metadata, how you handle abuse reports and what your retention and data handling policies say. Adding a partner list later usually means editing the federation allow list, opening the listener and updating DNS or certificates. The server name is different: it determines how user and room identifiers look, so changing it after users exist is a larger project. Confirm the reversibility of each step with the Synapse documentation for your version before you commit.
Should Synapse federation use port 8448 or port 443?
Port 8448 is the Synapse default, while delegation lets you keep federation traffic on port 443 and serve identities under your main domain. With port 8448, the federation listener is reachable directly, which means a separate firewall rule and certificate handling for that port. With delegation, a well-known response on the main domain points remote servers to the host that serves federation, so user IDs such as the @user form on your own domain can stay in place while the federation host sits behind a proxy on 443. The right choice depends on your existing proxy, your firewall policy and whether your identity domain must stay separate from the host name. Test both the discovery and the connection from an external server before you rely on either.
How do we limit Synapse federation to specific partner domains?
Use the federation_domain_whitelist setting, and also restrict the federation listener at the firewall. Synapse only federates with domains that appear in the list, and an empty list disables federation entirely. The Synapse documentation recommends firewalling the federation listener as well, so that a configuration mistake does not expose the port. After changing the list, test one allowed domain and one blocked domain from outside your network and record both results in the change ticket. Review the list whenever a partner changes its domain, and make sure the people who approve partner additions know how the firewall rule is kept in sync. Confirm the exact behavior of this setting for the Synapse release you run.
Does DeployOpen certify our federation setup for compliance?
No. DeployOpen prepares the configuration, controls and evidence, and independent auditors or certification bodies make any assessment. For organizations with confidentiality or regulatory requirements, the work can include documenting the federation policy, the allowed domain list, the firewall rules, the logging and the review process so that an auditor can examine them. The assessment itself, any audit report and any certification come from the auditor or certification body, not from DeployOpen. Ask your auditor which evidence they expect for federation controls before the work is scoped, so the deliverables match the questions they will ask.
Official Synapse and Matrix federation references
Before you finalize a federation decision, confirm each setting against the official Synapse documentation for the release you intend to run. The most useful starting points are the Synapse federation page, which explains default port 8448, delegation and server_name, and the Synapse configuration manual, which documents federation_domain_whitelist and the related listener settings. Treat these two pages as the reference for the policy you write, and record the documentation version you checked alongside your configuration review.
The Synapse workers documentation matters for federation policy even if you do not plan to scale out at first. It describes how the generic worker handles client, federation and event traffic, and how Redis relays replication between the main process and workers. If federation traffic will later move to dedicated worker processes, the listener and firewall rules you set now must still apply to whichever process serves port 8448 or port 443. Ask your platform team to map each federation listener to a process so the policy stays enforceable after any topology change.
The Matrix.org server ecosystem page lists homeserver implementations and their licenses, which helps you confirm that Synapse is the server you are configuring and that it is the one your policy assumes. Pair it with the Synapse releases page on GitHub, which is now hosted under the element-hq organization after the repository move. Check the release notes for each version you plan to deploy, because federation behavior and default settings can change between releases, and the release notes are where you will see those changes first.
The Synapse upgrade notes should be read before any change to federation settings, not only before a version upgrade. They describe database schema changes that can make rollback difficult, and they state that Synapse drops support for Python and PostgreSQL versions once upstream end of life is reached. Federation policy changes can require a restart or a configuration migration, so schedule them with the same change control you use for upgrades. Confirm the current minimum PostgreSQL and Python requirements in the notes for your target release.
For the Element Server Suite and Matrix Authentication Service references, confirm with Element which documentation applies to your edition and deployment model. If you plan to use the Element Server Suite, check its product page for the edition that matches your use, since the community and professional editions are described differently. Ask vendors and integrators to point to the exact pages they rely on for federation behavior, and keep those links in your architecture record so the next reviewer can verify the same statements.
How DeployOpen works on this
DeployOpen treats federation as a policy decision before it is a configuration task. We agree in writing which federation model fits your data control requirements, then implement it inside your own infrastructure and document it for the team that will run it.
How we scope
- Written scope names the federation model: open, a partner domain allowlist, or no federation at all.
- Scope records the server_name, delegation approach and whether port 8448 or port 443 will serve federation traffic.
- Scope lists the identity, client and bridge decisions that depend on the federation choice, so they are not left open.
How we build
- We configure federation_domain_whitelist or equivalent settings and test allowed and blocked domains against your policy.
- We set up delegation and listener firewalling so federation traffic reaches only the endpoints the policy permits.
- We verify federation behavior from outside your network and record the results as evidence for your review.
How we hand over
- Handover includes a written federation policy, the configuration files used, and the reasons behind each setting.
- Your administrators receive a runbook for adding or removing partner domains and for checking federation status.
- Deliverables are fixed in the written scope, so you know exactly what your team inherits at the end of the engagement.
How we support
- Ongoing support is available as a retainer and can cover reviews of federation settings after Synapse upgrades.
- Retainer work can include re-testing partner domain rules when your policy or partner list changes.
- Confirm with us during scoping which support tasks, response expectations and review cadence the retainer includes.
