This article is for X-Road versions >= 7.3.0. Instructions for older X-Road versions are available here.
Table of contents
1. Configuration of the Central Server
1.1 Logging in to the administration interface and creating initial configuration
The official Central Server installation guide is available at: https://github.com/nordic-institute/X-Road/blob/develop/doc/Manuals/ig-cs_x-road_6_central_server_installation_guide.md
After installing the Central Server the admin interface can be found at https://<CENTRAL_SERVER_URL>:4000. At the first time the self-signed certificate from the server needs to be accepted.
If you go to the URL right after the installation has finished, usually the background services have not started yet and an error message is returned.
Wait for a while and eventually the browser connects to the admin interface.
Enter the admin interface root user credentials created during the installation phase.
Press Log in.
In the initial configuration screen you need to input the following information:
Instance identifier
Central Serve address
PIN-code that protects the server's secret keys.
After completing the requested information, press Submit
The initial configuration is saved and the server outputs message: The Central Server Initialized! Now continue with the full configuration.
Initially, the admin interface displays multiple error messages but they will vanish while the configuration proceeds. At this point the errors can be ignored.
1.2 Adding member classes
Choose Settings -> System Settings -> Member Classes -> Add. Add suitable Member Class for the administrative organization and press Save.
The added Member Class shows in the list.
1.3 Adding certification service
Information about technical requirements for trust service providers is available here.
When using the test CA as a certification provider, please see the location of the CA root certificate and OCSP certificate, and OCSP URL at:
Choose Trust Services -> Add certification service.
Upload the certification service's root certificate and press Upload.
For test CA the following
CertificateProfileInfovalue must be used:ee.ria.xroad.common.certificateprofile.impl.FiVRKCertificateProfileInfoProvider.More information about certificate profiles is available here.
Press Save.
Open the details view of the new certification service by clicking the service name.
Choose OCSP Responders -> Add.
URL is the OCSP responder's address.
Upload the OCSP responder's certificate.
Press Save.
The Trust Services view after adding the certification service.
1.4 Adding time-stamping service
Information about technical requirements for trust service providers is available here.
When using the test CA as a time-stamping provider, please see the location of the TSA certificate and TSA URL at:
Choose Trust Services -> Timestamping Services -> Add timestamping service.
Add timestamping service URL.
Upload the timestamping service's certificate.
Press Add.
The screen after adding the timestamping service.
1.5 Adding the administrative organization and subsystem
Choose Members -> Add member.
Member name - the name of the administrative organization.
Member class - pick from the list.
Member code - organization identifier, e.g. business ID.
Press OK.
The screen after adding the organization.
Open the organisation details by clicking the organisation name.
For management services a subsystem is added to the organization. Choose Subsystems -> Add new subsystem.
Subsystem Code - enter the subsystem's name.
Press Add.
The screen after adding the subsystem.
1.6 Configuring the management services
Choose Settings -> System Settings -> Management Services -> Service Provider Identifier -> Edit.
Pick the subsystem that was added earlier.
Press Select.
The screen after configuring the subsystem for management services.
1.7 Adding the signing keys
Choose Global Configuration -> Internal Configuration -> Signing keys -> Log in.
Write the PIN-code that was chosen earlier.
Press Log in.
Choose Add key.
Define a friendly name for the key.
Press Add.
The screen after adding the internal signing key.
Choose Global Configuration -> External Configuration -> Signing keys -> Add key.
Define a friendly name for the key.
Press Add.
The screen after adding the external signing key.
The user interface error messages disappear after a small wait. The configuration of the Central Server is now finished.
2. Installing the Security Server for management services
The official Security Server installation guide is available at: https://github.com/nordic-institute/X-Road/blob/develop/doc/Manuals/ig-ss_x-road_v6_security_server_installation_guide.md
3. Configuring the Security Server for management services
3.1 Initial configuration
After installing the Security Server the admin interface is found at https://<SECURITY_SERVER_URL>:4000/. At the first time the self-signed certificate needs to be approved.
If you go to the URL right after the installation has finished, usually the background services have not started yet and an error message is returned.
Wait for a while and eventually the browser connects to the admin user interface. Enter the administrator user credentials created during the installation.
In the next screen a configuration anchor is requested.
Upload the configuration anchor from the Central Server's admin interface Global Configuration -> Internal Configuration → Anchor -> Download.
Press Upload.
Next the anchor upload needs to be confirmed.
Check that the Hash ja Generated correspond to the information on the Central Server.
Press Confirm.
Press Continue.
The Owner Member view includes the following fields:
Member Name - is auto completed when Member Code is added.
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.
Security Server Code - unique code identifying the Security Server.
Press Continue.
The Token PIN view includes the following fields:
PIN - the password that protects the Security Server's secret keys.
Repeat PIN - repeat the above PIN.
Press Submit.
The initial configuration was saved successfully.
3.2 Entering the PIN code
The Security Server asks for PIN code.
Follow the link Please enter softtoken PIN.
Clicking the links navigates to Keys and Certificates -> SIGN and AUTH Keys page.
Press SIGN and AUTH Keys -> TOKEN: SOFTTOKEN-0 -> Log in.
Enter PIN code.
Press Log in.
The red error message bar disappears.
3.3 Configuring the time-stamping service
Choose Settings -> System Parameters -> Timestamping Services -> Add.
Pick a timestamping service from the list.
Press Add.
3.4 Creating the certificate requests
Open the Keys and Certificates view.
Select TOKEN: SOFTTOKEN-0.
Press Add key.
Define an optional label for the key and press Next.
Please note that the authentication and sign certificate fields vary between different certificate profiles. If you are not using the certificate profile mentioned in this guide, the certificate fields are different.
Usage - SIGNING.
Client - select the organization that maintains the Central Server.
Certification Service - select the certification service that was defined on the Central Server.
CSR Format - select a suitable format for the certification service. NOTE: The test CA setup only accepts DER as input format.
Press Continue.
Organization name (O) - enter the name of the organization maintaining the Central Server.
Press Generate CSR.
The certificate request is downloaded to browser's download folder.
Press Done.
Select TOKEN: SOFTTOKEN-0.
Press Add key.
Define an optional label for the key and press Next.
Please note that the authentication and sign certificate fields vary between different certificate profiles. If you are not using the certificate profile mentioned in this guide, the certificate fields are different.
Usage - AUTHENTICATION.
Certification Service - choose the certification service that was defined on the Central Server.
CSR Format - select a suitable format for your certificate service. NOTE: The test CA setup only accepts DER as input format.
Press Continue.
Server DNS name (CN) - the Security Server's FQDN.
Organization name (O) - write the name of the organization maintaining the Central Server.
Press Generate CSR.
The certificate request is downloaded to browser's download folder.
Press Done.
When using the test CA as a certification provider, sign the certificate requests according to the instructions:
https://github.com/nordic-institute/X-Road/blob/develop/ansible/TESTCA.md#7-signing-certificates
3.5 Importing the certificates
First, import the authentication certificate.
Press Import cert.
Find the certificate using browser’s file picker dialog that opens after clicking Import cert.
Press Open.
The screen after importing the certificate. The authentication certificate is disabled initially.
Open the authentication certificate details view by clicking the certificate.
Press Activate and close the details view.
The authentication certificate is now activated.
Second, import the sign certificate.
Press Import cert.
Find the certificate using browser’s file picker dialog that opens after clicking Import cert.
Press Open.
The screen after importing the certificate. Sign certificate is good / registered.
3.6 Registering the authentication certificate
Press Register.
Enter the Security Server's FQDN.
Press Add.
The registration request of the authentication certificate is sent to the Central Server. The certificate transitions to state registration in progress.
Open the Central Server's admin interface.
Open the Management Requests view.
Approve the pending management request by clicking Approve.
Next, Approve management request confirmation dialog opens. Click Yes.
Automatic approval of management requests can be enabled by adding the following configuration in /etc/xroad/conf.d/local.ini on the Central Server:
[center]auto-approve-auth-cert-reg-requests=trueauto-approve-client-reg-requests=trueauto-approve-owner-change-requests=true
After changing the contents of the /etc/xroad/conf.d/local.ini configuration file, the xroad-center service must be restarted to apply the changes.
The management request has been approved and the list of pending management requests is empty.
View processed management requests by unchecking the Show only pending requests checkbox.
Return to the Security Server's admin interface.
Open Security Server Clients.
The owner organization status is REGISTRATION IN PROCESS, but it will soon change to REGISTERED.
The screen after successful registration:
3.7 Add subsystem for management services
Press Add subsystem.
Press Select subsystem.
Select the Security Server owner organization's row where the Subsystem Code is MANAGEMENT.
Press Add selected.
Press Add subsystem.
Press Yes.
The registration request fails because the management services have not been defined yet.
Open the Central Server's admin interface.
Open Settings -> System Settings.
Press Management Services -> Management Services' Security Server -> Edit.
Select the Security Server's owner organization from the list.
Press Select.
The next screen shows a message about successful registration.
Open the Security Server's admin interface.
Open Security Server Clients.
Wait until the status of MANAGEMENT subsystem changes to REGISTERED.
The screen after successful registration.
3.8 Configuring the management services
Select MANAGEMENT subsystem by clicking the subsystem name.
Open Services tab.
On the Central Server open Settings -> System Settings.
Copy to clipboard Management Services -> WSDL Address (later on you will also need Central Server address).
Go back to the Security Server and press Add WSDL.
Paste from the clipboard the WSDL address you copied and press Add.
The added WSDL shows disabled on the list.
Click the toggle switch on the right side of the WSDL row to enable the WSDL.
The screen after enabling the WSDL.
Press the > in front of the WSDL to show the services it contains.
Select authCertDeletion from the services list by clicking the service code.
Service URL - copy from the Central Server Settings -> System Settings -> Management Services -> Central Server address.
Timeout - leave to default.
Verify TLS Certificate - unchecked (remove the tick if checked).
Apply to All in WSDL - check all boxes to perform the changes to all the WSDL services.
Press Save.
Press Close.
Open Service Clients tab.
Press Add subject.
Select Security server owners from the list.
Press Next.
Select authCertDeletion, clientDeletion, clientReg and ownerChange.
Press Add selected.
The Service Clients list now shows the Security server owners.
Now all of the WSDL services have access rights defined and the management services are ready to be used.
4. Testing the management services
Open the Security Server's admin interface.
Open the Clients view.
Press Add subsystem.
Subsystem Code - enter TEST.
Press Add subsystem.
A dialog asking about subsystem registration opens.
Press Yes.
The subsystem TEST shows on the list. The status is REGISTRATION IN PROGRESS.
Open the Central Server's admin interface.
Open Management Requests.
Approve the first pending Add Client request by clicking Approve.
A confirmation dialog opens.
Press Yes.
The screen after accepting the management request.
Open the Security Server administrator user interface.
Wait until the status of TEST subsystem changes to REGISTERED.
The screen after the client registration has completed.
