Diagram
The control flow (top row) and the data flow (bottom row) are separate. The Central Server never sees the data.
Client organization
/r1/… or SOAP, with an X-Road-Client headerProvider organization
Sequence
POST /r1/MN/GOV/…/service, with an X-Road-Client header.
Server A signs the message with the organization's SIGN key.
A connects directly to server B using its AUTH certificate. Each side verifies the other via the global configuration and OCSP.
Server B checks the signature and that client's rights (ACL), then passes the request to the provider's system.
The response returns the same way, signed by B.
Both servers log the message and get a batch timestamp from the TSA. This later serves as evidence.
Identifiers
In X-Road, every organization, subsystem and service has a hierarchical identifier. The instance name is set once and can never be changed.
Member code = national registration number. The Estonian row shows how X-tee's operator is structured.
Protocol
client, id, protocolVersion./r1/{instance}/{class}/{code}/{subsystem}/{service}, X-Road-Client header.listClients, listMethods, allowedMethods, getOpenAPI.Security
AUTH — the server's TLS certificate (CN = server code). SIGN — the organization's signing certificate (O = class, CN = member code).
Responses refresh every 20 min and stay valid for 1 hour. If OCSP is down for more than an hour, message exchange stops — OCSP is the most fragile point.
Timestamps cover batches of the log, not each message. If the TSA is down for long, the server stops passing messages.
By default archived every 6 hours and deleted after 30 days. It can be stored encrypted. Every admin change goes into the audit log.
RSA 2048 by default. Software token or HSM. Lose the token PIN and the key cannot be recovered.
In the EU, the signature counts as an advanced electronic seal. A qualified seal requires an HSM and a qualified CA.
Network
Only 5500 and 5577 (plus 80 for ACME) are open to the internet. The admin interface on 4000 must never be exposed to the internet.
| Direction | Port | Purpose |
|---|---|---|
| Inbound | 5500 | Messages between Security Servers (mTLS) |
| Inbound | 5577 | OCSP responses between servers |
| Inbound · internal | 4000 | Admin UI and management API |
| Inbound · internal | 8080 / 8443 | From the organization's own information systems |
| Outbound | 4001 | Central Server (registration requests) |
| Outbound | 80 / 443 | Global configuration download, OCSP, TSA |
| Local | 5432 · 2080 | PostgreSQL · operational monitoring |
Operating system (7.8.x): Ubuntu 22.04 / 24.04 LTS, RHEL 8/9, or Docker. The Central Server runs on Ubuntu only. Minimum: 2 cores (AES), 4 GB RAM, 3 GB disk — in production, size for message-log growth.
How to join
Add the NIIS repository after checking its GPG key fingerprint, then install xroad-securityserver.
Import the anchor from the Central Server and verify its hash over a separate channel.
Enter the owner's class, code, server code and token PIN. The member must already be registered on the Central Server.
Without a TSA configured, every client registration request fails.
Generate AUTH and SIGN keys, have the CSRs signed by an approved CA, then import and activate the certificates.
Register the AUTH certificate with the Central Server and have the operator approve it. Then register each subsystem.
Add your OpenAPI or WSDL and grant access to specific clients.