Federation Configuration

Federation is currently in its final stability and performance tuning phase. While the feature is already suitable for evaluation and non-critical use cases, you may occasionally encounter intermittent behavior as we complete ongoing audits and optimizations. For this reason, we currently recommend avoiding Federation for mission-critical workloads until the final stabilization phase is complete.

This guide explains how to configure Federation in Rocket.Chat, including the required license validation, server identity, security controls, and governance policies that regulate how federated communication operates across Matrix-protocol servers (federated workspaces).

Prerequisites

Before enabling Federation, ensure that your workspace meets the following technical, licensing, and network requirements.

The .well-known discovery file is required when:

• your access domain and federation domain are different, or

• your Matrix service runs on a different hostname or port

Without this file, other homeservers may not be able to discover your federation endpoint, and federation may fail.

Configuring Federation

Follow these steps to enable Federation in your workspace:

Step 1: Enable Federation

To begin configuring Federation, open your workspace administration panel and navigate to Manage → Workspace → Settings → Federation

On this page, turn Enable native federation toggle ON to activate cross-server communication using the Matrix protocol. Once this toggle is enabled, the federation configuration fields become available.

Step 2: Set your federated domain (server identity)

In the Federated Domain field, enter the domain name that your server will use as its identity on the Matrix network. Example: acme.com

This domain is used to:

• Identify your workspace to other federated servers

• Build federated user IDs (for example: @user:acme.com)

• Allow remote servers to locate and verify your homeserver

Enter only the domain name in this field, and do not include http://,  https://, slashes, or any additional paths (for example, use acme.com, not https://acme.com/chat).

Step 3: Configure signing & server trust

Avoid changing or replacing the current signing keys unless absolutely necessary. Updating signing keys can invalidate existing signatures and may disrupt client trust relationships. Only rotate keys when required for security or compliance reasons.

Signing key algorithm

The signing key algorithm defines which cryptographic method is used to sign federation messages. Rocket.Chat follows the Matrix federation standard and uses Ed25519 as the recommended and default algorithm.

Ed25519 provides strong security with high performance and is the modern standard used across the Matrix ecosystem. While other algorithms such as RSA or HMAC-based options may exist in theory, Ed25519 should always be used, and changing the algorithm is not recommended for production or testing environments.

Signing key version

The signing key version identifies which specific signing key your server is using when it signs federation events. This version acts as a key ID that allows other servers to determine which public key should be used to verify a given signature.

Generating the signing key

The signing key must be generated externally using a secure cryptographic tool. For example, you can generate an Ed25519 key pair using OpenSSL:

openssl genpkey -algorithm Ed25519 -out signing.key
openssl pkey -in signing.key -pubout -out signing.pub

After generating the private key, convert it to base64 format and paste the encoded value into the Signing Key field in the Federation settings.

Step 4: Maximum number of members

This setting defines the maximum number of users from your workspace who are allowed to join a public room hosted on a remote federated server.

The default value is 100. Increasing this value allows larger groups to join external rooms but also increases server load, network traffic, and synchronization overhead. For early testing and controlled deployments, it is recommended to keep this value conservative.

Step 5: Domain allow list (optional)

The Domain Allow List lets you explicitly control which remote domains your workspace is allowed to federate with.

When this field is populated, your server will:

• Only federate with domains listed here

• Block all federation traffic from any other domains

Step 6: Event synchronization controls

These settings determine which real-time user activity signals are exchanged between federated servers. Enabling additional event types can improve the user experience but may also increase server and network load.

Process typing events

This setting controls whether typing indicators are synchronized across federated servers. When enabled, users in federated rooms can see when a remote participant is actively typing a message. When disabled, typing activity remains local to each workspace.

Enabling this feature increases the number of real-time events exchanged between servers and may slightly increase network and processing overhead.

Process presence events

This setting controls whether user presence information (such as online, offline, or away status) is synchronized between federated servers. When enabled, presence updates are exchanged in real time across workspaces. When disabled, presence remains local to each server and is not shared with federated participants.

Presence events generate frequent updates, especially at scale. Enabling this option may increase server load and network traffic, but it can be very useful when real-time presence visibility across organizations is needed.

Step 7: Room Access Controls

These settings define which types of rooms users in your workspace are allowed to join on remote federated servers. They help you balance accessibility with security, compliance, and data visibility.

Allow joining encrypted federated rooms

This setting controls whether users are allowed to join end-to-end encrypted rooms hosted on remote Matrix servers.

When enabled, users can join encrypted federated rooms, but Rocket.Chat cannot decrypt the messages exchanged in those rooms. As a result, encrypted content cannot be indexed, moderated, audited, or retained according to Rocket.Chat policies.

This option may affect compliance, security monitoring, and data-retention workflows. It’s best enabled when encrypted room access is an intentional part of your organization’s collaboration strategy.

Allow joining non-private rooms

This setting controls whether users are allowed to join public (non-private) rooms hosted on remote federated servers.

When enabled, users may discover and join public rooms on other servers. When disabled, access to public federated rooms is restricted, and users can only participate in rooms they are explicitly invited to.

During the Alpha phase, it is recommended to keep this setting disabled to reduce exposure to unmoderated external spaces and to maintain tighter control over federation activity.

Step 8: Save, validate, and test federation

After completing all required configuration fields, click Save to apply the federation settings to your workspace.

Once the configuration is saved, you should validate federation by performing a basic end-to-end test with a known remote federated server. This typically includes:

• Joining or creating a federated room

• Sending and receiving test messages

• Verifying that membership and message events are synchronized correctly

During testing, monitor your server logs for federation-related warnings or errors. If federation does not behave as expected, review your domain configuration, signing keys, and network accessibility.

At this stage, it is strongly recommended to test in a controlled environment before exposing federation to a large group of users.

Step 9: License & disablement behavior

Federation is a licensed, enterprise feature. Its availability and behavior are directly tied to both license status and the federation enablement setting.

When the license is valid and federation is enabled:

• Federated rooms operate normally

• Users can send and receive messages

• Invitations can be accepted and processed

• Room membership and events synchronize across servers

When the license expires or federation is disabled:

• All existing federated rooms immediately transition to a read-only state

• Users can view historical messages but cannot send new messages

• Invitations can no longer be accepted or created

• The message composer is replaced with a system notice explaining why federation is unavailable

This behavior ensures that data remains visible but prevents any unauthorized continuation of federated communication. Once the license is restored or federation is re-enabled, normal federated communication resumes automatically.