Documentation contents

Federation with another organization

Two organizations using Standard or Enterprise can share channels once administrators on both sides confirm that they trust each other.

Federation lets people message users at another organization that runs Gadka and invite them to shared channels. Administrators at both organizations must confirm that they trust each other.

Federation requires the Standard or Enterprise edition. In the Free edition, the Federation page shows Federation is not included in the license.

Before you begin

  • You need a Standard or Enterprise license key.
  • The server's public URL (api.public_url) must start with https://.
  • Each organization's server must be able to reach the other over the network.
  • You need a way to contact the other organization's administrator outside Gadka.

Enable federation on the server

Generate the key the server will use to sign requests to other servers.

sudo openssl genpkey -algorithm ed25519 -out /etc/gadka/federation-key.pem
sudo chown root:gadka /etc/gadka/federation-key.pem
sudo chmod 0640 /etc/gadka/federation-key.pem

Add the following settings to /etc/gadka/gadka.yaml.

federation:
  enabled: true
  signing_key_file: /etc/gadka/federation-key.pem

Restart the server with sudo systemctl restart gadka.

Exchange organization addresses

  1. Open Admin, then Federation.
  2. Under Your organization's address, click Copy address. The address looks like firma@gadka.example.com.
  3. Share it with the other administrator by phone or email and ask for their organization's address.

Add a trusted organization

  1. Click Add organization.
  2. Enter the Organization address and click Add.
  3. The status is Waiting for their approval until the other organization adds your address. It then changes to Active.

Permissions for the other organization

In the relationship details, under What you allow, choose which permissions to grant from Direct messages, Shared channels, Files and Presence visibility. Each organization sets its own permissions. Presence is visible only if both allow it.

What the other organization can see

  • People can see their direct conversations and the contents of shared channels they have accepted invitations to.
  • The organization that created a shared channel stores the channel and its files.
  • To find someone at another organization, you need their full email address. There is no directory of the other organization's users to browse.

Revoke trust or block a user

  • Revoke trust takes effect immediately. Users from the other organization lose access to shared channels, and can still read their direct conversations but cannot send new messages.
  • Block cuts off access for an individual user while keeping the relationship with the organization active.
  • Click Refresh keys only after the other administrator confirms through a separate channel that they have replaced their server's key.

Network requirements

Trusted organizations' servers must be able to reach /federation/v1/ and /.well-known/gadka-federation on your server. By default, the server connects only to public addresses. For a relationship with a server on a private network, select Server in a private network (on-prem). This option requires federation.allow_private_networks: true.