Setting up an X-Road Security Server
Security Server Installation, Registration and Configuration
Last updated
Was this helpful?
Security Server Installation, Registration and Configuration
Last updated
Was this helpful?
64-bit dual-core Intel, AMD or compatible CPU; AES instruction set support is highly recommended
2 CPU
4 GB RAM
10 GB free disk space (OS partition) and 20-40 GB free disk space on the “/var” partition
100 Mbps network interface card
This guide assumes one of the following:
Red Hat Enterprise Linux
RHEL8+
Ubuntu
20.04 LTS
22.04 LTS
Note: Installing and configuring an X-Road Security Server requires sudo
permissions on the host.
Running the X-Road Security Server in a container is outside the scope of this guide, but you can refer to the official for guidance.
The FQDN of a Security Server should easily identity the Tier and Owner:
IS-DEV
Development
xroad-dev.<member's domain>.is
IS-TEST
Testing / QA / UAT / Staging et.al.
xroad-test.<member's domain>.is
IS
Production
xroad-prod1.<member's domain>.is
xroad-prod2.<member's domain>.is
xroad
POSIX userThe X-Road Server should be run under a dedicated POSIX user, usually named xroad
Create this user by running the following command:
During installation, a dialog will appear asking for host and IP information for certificate generation. The latter set of the dialog will be for configuring certificates for the xroad-proxy-ui-api
.
Here it may be desirable to change the value from the auto-detected machine host name to a domain name used for accessing the Admin UI:
Before being able to import a Configuration Anchor, the Security Server IP and FQDN must be whitelisted by the operator of the Straumurinn X-Road Central Services.
To register a Security Server into Straumurinn, the following configuration values are required:
The public outgoing IP address of the server can be found with with the following command from a Security Server terminal session:
The xroad-securityserver-is
variant has the message logging disabled by default, from X-Road version 6.24.0 onwards.
Keep the the PIN secret. Keep it safe.
During the Security Server initial configuration, we need to generate a password called the "software token PIN".
The PIN is a 12 digit, alpha-numeric password:
If Auto-Login is not configured, the server will require manual entry of the Soft Token PIN during startup / restart, which can have implications for the Security Server's reliability.
To verify that auto-login PIN entry works as expected, you can try stopping and starting all the X-Road services like this:
Next, point your browser at the Security Server, on port 4000 and log in.
After anchor has been uploaded, it needs to be confirmed.
Ensure that the "Hash Generated" corresponds to the information on the Central Server.
Click [CONFIRM].
The Configuration Anchor has now been configured and should show you something like the following:
In the initial configuration screen input the values as follows.
Member Class - the Member Class of the organization that maintains the central server.
Member Code - the Member Code of the organization that maintains the central server.
Member Name - is auto completed when Member Code is added.
Security Server Code - unique code identifying the Security Server.
Use short-name for Server Code
Do not use FQDN, ".", "/" or "".
Some extensions use dots as separators, e.g. REST Adapter Service.
X-Road Message Protocol imposes some restrictions on the characters that can be used in X-Road identifiers. The following characters SHALL NOT be used in the identifier values:
Colon
Semicolon
Slash
Backslash
Percent
Path identifiers (such as /../)
Non-printable characters (tab, newline etc.)
PIN - the password that protects the security server's secret keys.
Repeat PIN - repeat the above PIN.
Keep the PIN secret. Keep it safe.
The initial configuration was saved successfully.
The security server asks for PIN code.
Click the Please enter soft token PIN link.
Clicking the link navigates to Keys and Certificates page.
Click [LOG IN] on the softToken
Service.
Enter PIN Code
Click [LOG IN] in the modal window.
The red error message bar should now disappear.
Go to: Settings > Timestamping Services and click [ADD]
Pick a time-stamping service from the list and click [OK.]
The message "Timestamping message added" should appear.
Navigate to "KEYS AND CERTIFICATES"
Click [ADD KEY]
Enter ”sign” for the "Key Label" and click [NEXT]
Fill out the form with the following values:
Usage: SIGNING
Client: Select the relevant Client from the dropdown.
CSR Format: PEM
Click [GENERATE CSR]
Click [DONE]
The CSR should be downloaded to browser's download folder.
If you are not already there, start by navigating to "KEYS AND CERTIFICATES"->"SIGN AND AUTH KEYS" of the Admin UI (see above).
Click [ADD KEY]
Enter “auth” and click [NEXT]
Choose AUTHENTICATON and change CSR Format to PEM
Fill out the form with the following values:
Usage: AUTHENTICATION
Certification Service: Select the appropriate certification service (there should only be 1)
CSR Format: PEM
Enter your Server DNS name (CN)
Press GENERATE CSR
The certificate request is downloaded to browser's download folder.
Now you can see that there are two keys in the overview, Sign and Auth.
Navigate to KEYS AND CERTIFICATIONS and click [IMPORT CERT].
Navigate to and select the .pem file containing your certificate.
Click the name of the certificate (test.xrd.island.is...) and press Activate
SCREENSHOT NEEDED
Finally press Register on the auth certificate and enter inn the FQDN of the server and press ADD
IS-DEV
Ísland.is to Skatturinn:
IS-TEST
Ísland.is to Skatturinn:
Check the .
NIIS maintains a guide for setting up Security Servers on Ubuntu and RHEL inside their knowlegebase, which you can find here:
While following the guide above, take care to override the official documentation with specific steps for the Icelandic environment (Straumurinn), outlined at
Once a Security Server has been successfully installed, the Admin UI can be accessed by pointing a web browser at .
To register, an email containing the values listed above the should be sent to the operator of the Straumurinn X-Road Central Server at
Have a look at the guide from X-Road. Some of the next steps are derived from there.
You will be asked to supply the PIN during .
For the PIN to be entered automatically when starting X-Road services, refer to the
Refer to the for information on enabling the health check endpoints.
Start by acquiring the Configuration Anchor for the X-Road network, found here:
Upload the environment's
The certificate request should be sent to .