LogoLogo
  • Technical Direction
  • Technical overview
    • Technical Implementation
    • API Design Guide
      • Data Definitions and Standards
      • Data Transfer Objects
      • Documentation
      • Environments
      • Error Handling
      • Example API Service
      • GraphQL Naming Conventions
      • Methods
      • Naming Conventions
      • Once Only Principle
      • Pagination
      • Resource Oriented Design
      • REST Request
      • REST Response
      • Security
      • Versioning
    • Ísland.is Public Web Data Flow
    • Code Reviews
    • Code Standards
    • Monorepo
    • Project Management
    • Teamwork
    • Architectural Decision Records
      • Use Markdown Architectural Decision Records
      • Use NX
      • Continuous Integration
      • CSS
      • Branching and Release Strategy
      • Error Tracking and Monitoring
      • What API Management Tool to Consider
      • Viskuausan Static Site Generator
      • Use OAuth 2.0 and OpenID Connect As Protocols for Authentication and Authorization
      • Unified Naming Strategy for Files and Directories
      • CMS
      • Open Source License
      • What Chart Library Should We Use Across Island.is?
      • What Feature Flag Service/application Should We Use at Island.is?
      • Logging, Monitoring and APM Platform
      • ADR Template
    • Log Management Policy
  • Products
    • Island.is Authentication Service
      • Terminology
      • Integration Options
      • Authentication Flows
      • Authorising API Endpoints
      • Session Lifecycle
      • Scopes and Tokens
      • Delegations
      • Configuration
      • Tools and Examples
      • Environments
      • Test IAS with Postman
    • Notifications / Hnipp
      • New Notification Setup Guide
      • Notifications service workflow overview
      • Email notifications
    • Pósthólfið
      • Security Checklist
      • Introduction
      • Skjalatilkynning API
      • Skjalaveita API
      • Sequence Diagram
      • Interfaces
    • Straumurinn (X-Road)
      • Architecture Guidelines for Service Providers and Consumers
      • Setting up an X-Road Security Server
        • Network Configuration
      • X-Road - Uppfærsla á öryggisþjónum
      • Straumurinn - Notkun og umsýsla
      • X-Road Central - current version
  • Development
    • Getting Started
    • Generating a New Project
    • Definition of done
    • Devops
      • Continuous Delivery
      • Database
      • Dockerizing
      • Environment Setup
      • Logging
      • Metrics
      • NextJS Custom Server
      • Observability
      • Operations Base Principles
      • Security
      • Service Configuration
      • Support
    • AWS Secrets
    • Feature Flags
    • Documentation Contributions
    • Defining Monorepo Boundaries With Tags
    • OpenAPI
    • Code Generation
    • Workspace Settings (Deprecated)
    • External Contributions
  • REFERENCE
    • Problems
      • 400 Validation Failed
      • 400 Attempt Failed
      • 403 Bad Subject
      • 400 500 Template API Error
    • Glossary
  • Misc
    • Guide: Adding a Payment Step to an Application
    • Guide: Enable Organisations to Make Requests to an Application
    • README Template
Powered by GitBook
On this page
  • Hardware requirements
  • Operating System Requirements
  • Network Configuration
  • FQDN Requirements
  • Installing X-Road
  • Provision the xroad POSIX user
  • Follow the installation guide
  • Registration
  • Required configuration for registration
  • Registration contact
  • Post-registration steps
  • Disable message payload logging
  • Software Token PIN
  • Ensure if all services are up and running
  • Enable health check endpoint
  • Initial Configuration
  • Configuration Anchors
  • Owner Member
  • Software Token PIN
  • CSR certificates
  • Final steps
  • Configure Timestamping Services
  • Configure SIGN and AUTH Keys
  • Import Certificates
  • Confirm communication between two security servers
  • Removal of Security Server

Was this helpful?

  1. Products
  2. Straumurinn (X-Road)

Setting up an X-Road Security Server

Security Server Installation, Registration and Configuration

PreviousArchitecture Guidelines for Service Providers and ConsumersNextNetwork Configuration

Last updated 7 months ago

Was this helpful?

Hardware requirements

  • 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

Operating System Requirements

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 in a container

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.

Network Configuration

FQDN Requirements

The FQDN of a Security Server should easily identity the Tier and Owner:

Environment
Tier
FQDN Template

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

Installing X-Road

Provision the xroad POSIX user

The X-Road Server should be run under a dedicated POSIX user, usually named xroad

Create this user by running the following command:

sudo useradd \
--system \
--home /var/lib/xroad \
--no-create-home \
--shell /bin/bash \
--user-group \
--comment "X-Road system user" \
xroad

If that user will be used for interactive SSH log-ins, then we must ensure that the Security Server PIN (see below) doesn't get cleared (even though auto-login is configured), by running the following command:

loginctl enable-linger xroad

Follow the installation guide

Certificate generation

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:

Registration

Required configuration for registration

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:

1. Outgoing IP Address of the Security Server

The public outgoing IP address of the server can be found with with the following command from a Security Server terminal session:

$ curl ifconfig.me

2. FQDN of the Security Server

Refer to the section about FQDN Requirements.

3. Member's Kennitala / SSN

Registration contact

Example email for registering a Security Server to Central.

Post-registration steps

Disable message payload logging

The xroad-securityserver-is variant has the message logging disabled by default, from X-Road version 6.24.0 onwards.

Software Token PIN

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:

Configure Auto-Login PIN entry functionality

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.

Test auto-login PIN entry functionality

To verify that auto-login PIN entry works as expected, you can try stopping and starting all the X-Road services like this:

for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api ;\
do \
   echo "stopping $i"; \
   sudo service $i stop; \
done;
sudo systemctl list-units "xroad*"
for i in xroad-confclient xroad-proxy xroad-signer xroad-monitor xroad-opmonitor xroad-proxy-ui-api; \
do \
   echo "starting $i"; \
   sudo service $i start; \
done

Ensure if all services are up and running

sudo systemctl list-units "xroad*"

Enable health check endpoint

Initial Configuration

Configuration Anchors

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:

Owner Member

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.)

Software Token PIN

  • 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.

CSR certificates

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.

Final steps

Configure Timestamping Services

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.

Configure SIGN and AUTH Keys

SIGN Key

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.


The AUTH key

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.

Import Certificates

Navigate to KEYS AND CERTIFICATIONS and click [IMPORT CERT].

Import the AUTH Certificate

Navigate to and select the .pem file containing your certificate.

Activate auth signed certificate

Click the name of the certificate (test.xrd.island.is...) and press Activate

SCREENSHOT NEEDED

Import the SIGN Certificate

Finally press Register on the auth certificate and enter inn the FQDN of the server and press ADD

Confirm communication between two security servers

curl --insecure -H "X-Road-Client: IS-TEST/COM/5302922079/Origo-client" "
https://origo-staging.xroad.coldcloudlab.com/r1/IS-TEST/GOV/7005942039/VMST-Protected/APIS/company?name=origo
"

IS-DEV

Ísland.is to Skatturinn:

curl -H "X-Road-Client: IS-DEV/GOV/10000/island-is-client" "http://localhost:8080/r1/IS-DEV/GOV/10006/Skatturinn-Protected/APIS-v1/company?name=skatturinn"

IS-TEST

Ísland.is to Skatturinn:

curl -H "X-Road-Client: IS-TEST/GOV/5501692829/island-is-client" "http://localhost:8080/r1/IS-TEST/GOV/5402696029/Skatturinn-Protected/APIS-v1/company?name=skatturinn"

Removal of Security Server

Ubuntu

#!/bin/bash

set -x
sudo apt-get purge xroad-base
sudo apt-get autoremove
sudo rm -rf /etc/xroad
sudo rm -rf /usr/share/xroad
sudo rm -rf /var/lib/xroad
sudo rm -rf /var/log/xroad
sudo rm -rf /var/tmp/xroad
sudo apt-get purge nginx
sudo -u postgres dropdb messagelog
sudo -u postgres dropdb serverconf
sudo -u postgres dropdb op-monitor
sudo -u postgres psql -c "drop user serverconf"
sudo -u postgres psql -c "drop user messagelog"
sudo -u postgres psql -c "drop user opmonitor"
sudo -u postgres psql -c "drop user serverconf_admin"
sudo -u postgres psql -c "drop user messagelog_admin"
sudo -u postgres psql -c "drop user opmonitor_admin"
sudo apt-get --purge remove postgresql\*
sudo rm -rf /etc/postgresql/
sudo rm -rf /var/lib/postgresql
sudo userdel -r postgres

RHEL

#!/bin/bash

set -x

sudo yum remove xroad-base
sudo rm -rf /etc/xroad
sudo rm -rf /usr/share/xroad
sudo rm -rf /var/lib/xroad
sudo rm -rf /var/log/xroad
sudo rm -rf /var/tmp/xroad
sudo yum remove nginx
sudo -u postgres dropdb messagelog
sudo -u postgres dropdb serverconf
sudo -u postgres psql -c "drop user serverconf"
sudo yum remove postgresql

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 .

Security Server Sidecar User Guide
How to Set Up a Security Server?
https://github.com/digitaliceland/Straumurinn
https://SECURITYSERVER:4000/
hjalp@ok.is
Security Server initial configuration
https://en.wikipedia.org/wiki/Personal_identification_number
https://en.wikipedia.org/wiki/ISO_9564#PIN_length
X-Road: Autologin User Guide
Health check service configuration
https://github.com/digitaliceland/Straumurinn/tree/master/Anchor
https://github.com/nordic-institute/X-Road/blob/6d60774c0b4e5368e70943c17a2ae6dfaa513259/doc/Protocols/pr-mess_x-road_message_protocol.md#27-identifier-character-restrictions
https://github.com/nordic-institute/X-Road/blob/6d60774c0b4e5368e70943c17a2ae6dfaa513259/doc/Protocols/pr-rest_x-road_message_protocol_for_rest.md#48-identifier-character-restrictions
hjalp@ok.is
Network Configuration sub-page
Initial Configuraion (see below)
configuration anchor.
Example email for registering a X-Road Security Server to Central
The X-Road Security Server Login Screen
Step 1 of the Initial Configuration Wizard, which allows the User to upload a Configuration Anchor
Configuration Anchor Confirmation Dialog
A successfully configured Configuration Anchor
Step 2 of the Initial Configuration Wizard, which allows the User to configure the Owner Member of the Security Server
Step 3 of the Initial Configuration Wizard, which allows the USer to set the Software Token PIN.
Configuration window for adding members, clients or subsystems
An X-Road Security Server Admin UI page showing a red banner with the message "Please enter soft token PIN" along with a button for logging in with the PIN
Logging in with PIN Code
The Settings -> System Parameters page which shows the empty Timestamping Services.
A modal for adding a Timestamping Service.
Admin UI: The Settings -> System Parameters page which shows that aTimestamping service has been added
The Keys and Certificate Page
The wizard for generating a certificate signing key
The CSR Details page inside the Add Key wizard.
The Generate CSR page inside the Add Key wizard
Final confirmation page of the Add Key wizard
An overview of SIGN and AUTH keys, showing that a CSR for the SIGN key has been created.
Part 1 of the The Add Key wizard, showing "Key Label" being set to "auth"
Part 2 of the The Add Key wizard: CSR details
Part 3 of the Add Key Wizard: Generate CSR
Final confirmation page of the Add Key wizard
An overview of SIGN and AUTH keys, showing that a CSR for both the SIGN and AUTH keys have been created.
The "KEYS AND CERTIFICATIONS" and screen overlaid by a MacOS File System Browser highlighting a .pem file.
The "SIGN AND AUTH KEYS" showing a successfully imported AUTH Certificate
A "Registration request" modal which accepts the Security Server DNS name
"SIGN AND AUTH KEYS" Screen showing that the status of AUTH Certificate is "Registration in progress"
"SIGN AND AUTH KEYS" Screen showing that both SIGN and AUTH Certificates have been Registered.