Getting Started
- Petteri Kivimäki
The best way to get started with X-Road is to get familiar with the overall concept and try out the software in practice. More information about X-Road and links to additional resources can be found at:
In addition, it is recommended to read the following documents before getting started on hands-on level:
How to setup your own environment
The easiest way to install your environment is to use the Ansible script available here. Please use the X-Road vanilla variant and the official X-Road package repository.
Starting from X-Road 7.0.0 the Security Server supports Docker. The Docker image is available on Docker Hub.
Once all the components are up and running, complete the configuration process following these instructions.
X-Road Bug Bounty Environment
X-Road bug bounty environment is a pre-configured X-Road environment that is publicly accessible to any researcher participating in the X-Road bug bounty program. Performing testing is allowed in this environment. However, the configuration of the environment is static and researchers have read-only access to the configuration.
X-Road bug bounty environment is a fully functional X-Road environment that consists of:
Central Server (CS)
Security Servers (SS) x2
Test services (IS)
Trust services (CA, OCSP, TSA)
There are three registered member organisations in the environment:
NIIS - X-Road operator
Test company - service consumer
Test agency - service provider
Accessing Security Servers
NIIS is the owner of Security Server #1, and Test agency the owner of Security Server #2. The test services are published on Security Server #2 and they can be consumed via Security Server #1. Security Server #1 is also the management Security Server connected to the Central Server.
Central Server's Security Server + Service consumer's Security Server:
Service provider's Security Server:
Username for the UI is xrd and password is secret. When logging in for the first time there's a warning message, because the self-signed certificate of the Security Server UI needs to be accepted.
The credentials are read-only - it is not possible update Security Servers' configuration. Also, it's not possible to get shell access to the Security Server hosts.
Invoking Test Services
Test services are published on Security Server #2 and they can be consumed via Security Server #1. There are test services available via both SOAP and REST interfaces. Test services can be invoked in multiple ways, e.g. command line using curl, Firefox RESTClient addon.
SOAP Services
There are two test services available: getRandom and helloService. GetRandom does not take any parameters and it returns a random number between 1 and 100 (example request). HelloService takes a name as a parameter and returns a greeting with the given name (example request). The test services can be invoked through Security Server's #1 SOAP interface at:
https://niisss01.bugbounty.x-road.global
SOAP requests must be submitted using HTTP POST method and content-type must be "text/xml". The examples below illustrate how the test services and listMethods meta service can be invoked using curl.
getRandom
curl -d @getRandom.xml --header "Content-Type: text/xml" -X POST https://niisss01.bugbounty.x-road.systems -k
helloService
curl -d @helloService.xml --header "Content-Type: text/xml" -X POST https://niisss01.bugbounty.x-road.systems -k
listMethods
curl -d @listMethods.xml --header "Content-Type: text/xml" -X POST https://niisss01.bugbounty.x-road.systems -k
Example requests can be downloaded at:
REST Services
REST services can be consumed using the X-Road Message Protocol for REST. The environment provides one REST API for testing purposes. The API is a public API providing open data, and it's owned and maintained by NIIS. The service description of the API is available here.
The test services can be invoked through Security Server's #1 REST interface at:
https://niisss01.bugbounty.x-road.systems/r1/
Requests must be submitted using the HTTP method and content-type required by the endpoint to be invoked. The examples below illustrate how to invoke the test services using curl. Other available endpoints can be discovered from the service descriptions.
list of X-Road environments
current statistics of a selected environment
get API description