The year 2023 is ending, and it's time to publish X-Road 7.4.0! The previous version, 7.3.0, was released in June, and it provided a new Central Server UI and management REST API. Version 7.4.0 includes several improvements for the Central Server, but the Security Server hasn’t been forgotten either.
The beta version is already out, and the official release version will be published in December 2023. The release notes are available here. Please note that the beta version doesn’t include all the changes mentioned in the release notes.
Let’s see what the highlights of the version 7.4.0 are!
Publishing global configuration over HTTPS
Until now, the Central Server and Configuration Proxy have only supported publishing global configuration over HTTP. Since the global configuration is signed, its integrity and authenticity are guaranteed despite lacking HTTPS support. Nevertheless, securing the global configuration download with HTTPS helps to maintain the privacy of the global configuration data.
A new private key and a self-signed TLS certificate are created automatically when installing a new Central Server or upgrading an existing installation from an older version. After the installation or upgrade, the Central Server Administrator must manually apply for a TLS certificate from a trusted Certificate Authority (CA) and then configure the certificate. This step is required because the Security Server does not trust the new automatically generated self-signed certificate by default. The Security Server supports disabling certificate verification, but disabling it in production environments is not recommended.
Starting from version 7.4.0, the global configuration will be available on the Central Server and Configuration Proxy ports 80 and 443. The old HTTP endpoint on port 80 guarantees that older Security Servers not supporting downloading global configuration over HTTPS continue to work normally. Also, the new Security Servers that support downloading global configuration over HTTPS will fall back to HTTP if the TLS certificate of the new HTTPS endpoint is not configured correctly.
Changes in the global configuration download ports may cause changes to firewall configuration on the Central Server, Configuration Proxy and Security Server. Inbound traffic from the Security Servers to port 443 must be allowed on the Central Server and Configuration Proxy. Similarly, outbound traffic to the Central Server and Configuration Proxy port 443 must be allowed on the Security Servers.
When upgrading the Central Server from version < 7.4.0 to version >= 7.4.0, the configuration anchor must be re-generated, distributed to all the Security Server administrators through an external channel (e.g., email) and imported to each Security Server to enable downloading global configuration over HTTPS. Without the new configuration anchor Security Servers will continue to download global configuration over HTTP.
Enforcing new key creation when generating CSR on the Security Server
A good security practice is creating a new key pair when applying for a new authentication or a sign certificate on the Security Server. Starting from version 7.4.0, the Security Server supports enforcing new key creation when generating a certificate sign request (CSR) on the Security Server. The feature is enabled by default, which means that it's not possible to generate a new CSR for a key that already has an existing certificate. The feature can be disabled by setting the “proxy-ui-api.allow-csr-for-key-with-certificate” system property to true on the Security Server.
Configuring a minimum required client Security Server version
From version 7.4.0, service providers can configure a minimum required X-Road software version for client Security Servers. It means that client Security Servers older than the configured version cannot access services anymore.
Service providers can configure the required minimum version using the “proxy.server-min-supported-client-version” system property. The property has no value by default, meaning a minimum version hasn't been set. Instead, when the value is set, all the minor and patch versions starting from the configured version are approved.
X-Road Operators may set this value in the country-specific meta packages, e.g., Estonia and Finland are setting the value to the three latest versions, which means that requests that are originating from client Security Servers older than version 7.2.0 are not accepted anymore in the Estonian and Finnish X-Road ecosystems. The value is rolling, meaning it changes for every X-Road minor version, e.g., when version 7.5.0 is released, the minimum supported version is 7.3.0.
Changes in default client information system communications ports
The default client information system inbound communication ports are changed from 80 to 8080 and from 443 to 8443 on Ubuntu-based Security Servers. In this way, the default ports are consistent regardless of the hosting operating system.
The change is only applied to new installations, and existing ones are unaffected by it. Also, if custom ports have been configured locally by the Security Server administrator, they are unaffected.
X-Road Operators may set the default port values in the country-specific meta packages. The Estonian ecosystem uses ports 80 and 443 by default for new installations after the change. In other words, the Estonian X-Road users organisations are unaffected by the change.
LDAP group mapping support
The Central Server and Security Server administrator user permissions are managed using X-Road-specific Linux groups mapped to X-Road user roles. An administrator must be a member of the X-Road-specific groups to access the management UI.
Starting from version 7.4.0, it’s possible to map additional Linux groups to X-Road user roles using the “proxy-ui-api.complementary-user-role-mappings” and “admin-service.complementary-user-role-mappings” system properties. It enables granting administrators permissions to the management UI using existing Linux groups instead of adding administrators to the X-Road-specific groups. In this way, existing Linux groups can be mapped to the X-Road user roles, and there's no need to change users' groups.
Rotating global configuration sign keys
The Central Server global configuration sign keys are included in the configuration anchor imported to the Security Server. Using the information in the anchor, the Security Server can verify the global configuration signature. Suppose the sign keys are rotated. In that case, a new configuration anchor must be generated on the Central Server, distributed to all the Security Server administrators through an external channel (e.g., email) and imported to each Security Server. Only after that, the changes are applied by each Security Server.
Starting from version 7.4.0, the Central Server global configuration sign keys are included in the global configuration. Thanks to this, rotating the sign keys is possible without importing a new version of the configuration anchor to each Security Server. Instead, the Security Server gets the updated configuration information from the global configuration directly and applies it immediately.
Importing the configuration anchor to the Security Server manually is also possible. It's required when the Security Server is initialised for the first time and when a Security Server has been offline or turned off when the global configuration sign key has been rotated.
Disabling a subsystem temporarily
Disabling a subsystem temporarily enables the Security Server administrator to disable a subsystem so that all the services added under the subsystem cannot receive requests. If the same subsystem is registered on multiple Security Servers, disabling the subsystem on one Security Server doesn’t affect the others. When a subsystem is disabled, the association between the subsystem and the Security Server where the subsystem is disabled is not visible to other Security Servers in the ecosystem. This applies to the local and federated ecosystems.
Instead, disabling a subsystem doesn't change any configuration items regarding the subsystem or its services. It makes the association between the Security Server and subsystem invisible to other Security Servers so that they cannot send requests to it. Similarly, a disabled subsystem cannot be used as a service client either.
Disabling and enabling a subsystem has a delay of a couple of minutes when the default configuration is used. During the delay, the subsystem may still receive service requests. However, the requests are not forwarded to the service provider information systems by the Security Server. Instead, all received requests will fail and an error message is returned to the service consumer. This is because the subsystem state is maintained on the Central Server, and updating it requires the Security Server to communicate with the Central Server. The length of the delay depends on the global configuration generation interval on the Central Server and the global configuration download interval on the Security Server. Other Security Servers become aware of a change in a subsystem’s state only after they download an updated version of the global configuration. Therefore, they may try to contact services under a disabled subsystem during the delay period.
Changing the Security Server address
The Security Server address is added to the Central Server when the authentication certificate is registered. Before version 7.4.0, updating the address afterwards required the Security Server administrator to contact the Central Server administrator over some external channel, e.g., email. Instead, starting from version 7.4.0, updating the address using the Security Server administrator UI or management REST API is possible.
The Security Server administrator can update the Security Server address by using the Security Server administrator UI and management REST API. The change is approved automatically by the Central Server and doesn't require manual approval from the Central Server administrator. By default, the change becomes visible to all the Security Servers in the ecosystem within a couple of minutes. However, the length of the delay depends on the global configuration generation interval on the Central Server and the global configuration download interval on the Security Server.
Migrate from Akka to gRPC
In September 2022, Lightbend announced that Akka, one of the third-party open-source libraries that X-Road heavily depends on, would change its licensing model. The new licensing model is commercial, but open-source projects meeting specific criteria may apply for an exception. However, the conditions of the license granted to open-source projects differ from the Apache 2.0 open-source license that Akka used before the change. From X-Road's perspective, the new license includes some unfavourable conditions, so Akka has been replaced with gRPC in X-Road.
Because of the change, any Akka-related system properties are not supported anymore starting from version 7.4.0, e.g., “<component>.akka.remote.artery.advanced.maximum-frame-size”. If Akka-related system properties have been used to override Akka’s default configuration values, they should be manually removed from the configuration.
Technical changes and upgrades
Besides functional changes and new features, several more technical changes have also taken place under the hood. The UI framework has been upgraded from Vue 2 to Vue 3, and the Spring Boot backend framework has been upgraded from version 2 to 3.
Also, the supported Java version has been upgraded from Java 11 to Java 17. The new Java version is installed automatically on other supported platforms except Red Hat Enterprise Linux 7 (RHEL7). On RHEL7, the Security Server administrator must manually configure a new package repository. More information about the upgrade process will be available in the release notes.
Other improvements and updates
Besides the already-mentioned features, version 7.4.0 includes many other minor improvements and updates. For example, a new command line tool to verify message log archive hash chains, remove deprecated rate limiting parameters on the Security Server, improve the Central Server UI, publish REST services using OpenAPI 3.1, replace the SHA-1 hashing algorithm with SHA-256, and much more. To fully understand all the changes, please review the release notes document.
What’s next?
Initially, support for automated certificate management through the Automatic Certificate Management Environment (ACME) protocol was scheduled for version 7.4.0. Unfortunately, support for ACME didn't make it to version 7.4.0, but it will be included in version 7.5.0 instead. Other changes that will be introduced in version 7.5.0 include but are not limited to, support for Ubuntu 24.04 LTS and support for Red Hat Enterprise Linux (RHEL) 9. Version 7.5.0 will be released during Q2 in 2024.
At the same time, when developing X-Road 7, NIIS is already working on the next X-Road major version – X-Road 8. If you’re interested in hearing more about the topic, please check out the talk that I delivered at the X-Road Community Event 2023 in September. More news regarding X-Road 8 will be published soon. Stay tuned!