How to Configure Federation Between Two X-Road Ecosystems?

X-Road provides built-in support for cross-ecosystem data exchange through federation, which means joining two X-Road ecosystems together. Members of federated ecosystems can publish and consume services with each other as if they were members of the same ecosystem. In practice, members can use the same Security Server for both intra-ecosystem and inter-ecosystem data exchange.

Technical Constraints

In order to federate two X-Road ecosystems, the following technical conditions must be met:

• The federated ecosystems must have unique instance identifiers. Two ecosystems with the same identifier cannot be federated.

• Approved Certificate Authorities (CAs) used by the federated ecosystems must have different Common Name (CN) values. Using CAs that have the same Common Name is not supported.

• Both instances must have each other's Certificate Profile Info implementation in the classpath. If both instances use the same X-Road version and the official installation packages distributed by NIIS, this is guaranteed. However, if one of the instances uses customised installation packages, this cannot be guaranteed.

Prerequisites

• Before setting up federation, the ecosystems to be federated must be initialised and fully operational. More information on initialising a single ecosystem is available here.

• Ports 80 and 443 of the Central Servers in the federated ecosystems must be accessible to the Security Servers of both ecosystems.

• Ports 80 and 443 of each Central Server in a federated ecosystem must be accessible from the Central Servers of the other federated ecosystems.

• Security Servers must allow incoming connections on ports 5500 and 5577 from the Security Servers of data exchange partners in the other ecosystem.

Setting Up Federation

Enabling federation and establishing trust between two X-Road ecosystems requires exchanging external configuration anchors between the Central Servers of the ecosystems and enabling federation on the Security Servers.

On the Central Servers

1. Download the External Configuration Anchors from both Central Servers (Global Configuration → External Configuration).

2. Upload the External Configuration Anchors to the Central Servers (Global Configuration → Trusted Anchors):

   1. The External Configuration Anchor from Central Server A is uploaded to Central Server B.

   2. The External Configuration Anchor from Central Server B is uploaded to Central Server A.

On the Security Servers

On the Security Server, federation is disabled by default and must be enabled manually. The following steps must be completed separately on each Security Server that needs to exchange data with members of the federated ecosystem.

1. Establish an SSH connection to the Security Server.

2. Open the /etc/xroad/conf.d/local.ini configuration file for editing.

3. Add the federated instance's instance identifier to the allowed federations list:

4. Restart the xroad-confclient and xroad-proxy services to apply the changes:

Federation is now enabled at both the ecosystem level and the Security Server level.

Testing and Verification

The federation configuration can be tested using the Connection Testing feature on the Security Server.

1. Go to Diagnostics → Connection Testing on the Security Server.

2. Locate the Other Security Server section on the page.

3. Select any available source client from the Client menu.

4. Select REST as the request type.

5. From the Target Instance menu, select the instance identifier of the federated ecosystem.

   1. If the menu contains only the instance identifier of the Security Server's own ecosystem, federation is not yet enabled. In that case, recheck the configuration in the /etc/xroad/conf.d/local.ini configuration file and make sure to restart the configuration proxy and proxy services to apply the changes.

6. Select any target client from the Target Client menu.

7. Click Test to verify that the connection between the source client and target client works.

   1. If the test request fails, check that the consumer Security Server is allowed to access ports 5500 and 5577 on the target Security Server.

If the Security Server does not provide the Connection Testing feature, verification can also be performed manually by sending a listMethods metaservice request to a client in the federated ecosystem using your preferred HTTP client (e.g., curl). For example:

 Related articles