How to Configure Central Server (version >= 7.3.0)?

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

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.

  • Choose Trust Services -> Add certification service.

  • Upload the certification service's root certificate and press Upload.

  • For test CA the following CertificateProfileInfo value 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

  • 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

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.

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

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

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.

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.