Security Server Docker Image that allows you to easily try X-Road is now available, so give it a try 1

Introduction

X-Road is a technology for information sharing used between Estonian government agencies and companies (banks, etc.) that cooperate with government agencies.

The source code of X-Road is at github.com/nordic-institute/X-Road, but there weren't many Docker Images or packages that worked immediately after downloading, so there weren't many articles about using it. did.

Recently, [Planetway has released a Docker Image that makes it easy to try X-Road \ hub.docker.com ]. In this article, for those who are new to X-Road, we will start by trying out X-Road with a little prior knowledge.

\ # full disclosure I'm from Planetway

Launch X-Road Security Server with docker-compose up

The Docker Image is open to the public. Anyway, let's launch it locally.

Create a working directory and copy the contents of the Docker Hub documentation to create a docker-compose.yml file.

% cat docker-compose.yml
version: '3.7'

services:
  ss01:
    image: planetway/xroad-securityserver:6.24.1-1
    command: bash -c "/files/initdb.sh && /files/cmd.sh"
    depends_on:
      - postgres
    environment:
      # JP-TEST or JP
      - PX_INSTANCE=JP-TEST
      - PX_MEMBER_CLASS=COM
      - PX_MEMBER_CODE=0170121212121
      - PX_SS_CODE=qiita-demo-01
      - PX_TSA_NAME=TEST of Planetway Timestamping Authority 2020
      - PX_TSA_URL=https://tsa.test.planetcross.net
      - PX_TOKEN_PIN=jXq+rlg2VS
      - PX_ADMINUI_USER=admin
      - PX_ADMINUI_PASSWORD=Secret222
      - POSTGRES_HOST=postgres
      - POSTGRES_PORT=5432
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - PX_SERVERCONF_PASSWORD=serverconf
      - PX_MESSAGELOG_PASSWORD=messagelog
      - PX_OPMONITOR_PASSWORD=opmonitor
      - PX_POPULATE_DATABASE=true
      - PX_ENROLL=true
    ports:
      - "2080:2080"
      - "4000:4000"
      - "5500:5500"
      - "5577:5577"
      - "5588:5588"
      - "8000:80"
      - "8443:443"
    volumes:
      # .p12 files and keyconf.xml
      - "px-ss-signer:/etc/xroad/signer"
      # mlog.zip files are stored here, and ./backup contains backups
      - "px-ss-xroad:/var/lib/xroad"

  postgres:
    image: postgres:10
    environment:
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"
    volumes:
      - "px-ss-postgres:/var/lib/postgresql/data"

volumes:
  px-ss-postgres:
  px-ss-signer:
  px-ss-xroad:

In the Docker Hub document, the place where the environment variable is omitted as ... is filled in appropriately for the time being.

PX_SS_CODE is a unique string that represents the Security Server in the X-Road member (the organization that participates in X-Road). When copying and pasting from here, change it to a unique character string.

Then docker-compose up to start Security Server and PostgreSQL together.

% docker-compose up
Creating network "px-ss-docker_default" with the default driver
Creating px-ss-docker_postgres_1 ... done
Creating px-ss-docker_ss01_1     ... done
Attaching to px-ss-docker_postgres_1, px-ss-docker_ss01_1
postgres_1  | The files belonging to this database system will be owned by user "postgres".
postgres_1  | This user must also own the server process.
postgres_1  |
postgres_1  | The database cluster will be initialized with locale "en_US.utf8".
postgres_1  | The default database encoding has accordingly been set to "UTF8".
postgres_1  | The default text search configuration will be set to "english".
postgres_1  |
postgres_1  | Data page checksums are disabled.
postgres_1  |
postgres_1  | fixing permissions on existing directory /var/lib/postgresql/data ... ok
postgres_1  | creating subdirectories ... ok
postgres_1  | selecting default max_connections ... 100
postgres_1  | selecting default shared_buffers ... 128MB
postgres_1  | selecting default timezone ... Etc/UTC
postgres_1  | selecting dynamic shared memory implementation ... posix
postgres_1  | creating configuration files ... ok
ss01_1      | 2021-01-11 09:00:06,566 Creating /var/lib/xroad/backup
ss01_1      | 2021-01-11 09:00:06,655 Generating new internal.[crt|key|p12] files
ss01_1      | /CN=0874c65254b7 -subj
ss01_1      | Generating a RSA private key
ss01_1      | ............................................................+++++
ss01_1      | ............+++++
ss01_1      | writing new private key to '/etc/xroad/ssl/internal.key'
ss01_1      | -----
ss01_1      | 2021-01-11 09:00:07,004 Generating new proxy-ui-api.[crt|key|p12] files
...
#After waiting for a while
ss01_1      | {"timestamp":"2021-01-11T09:03:10.183Z","level":"INFO","thread":"main","logger":"org.springframework.boot.web.embedded.tomcat.TomcatWebServer","message":"Tomcat started on port(s): 4000 (https) with context path ''","context":"X-Road Proxy Admin REST API"}

When the last line of ↑ comes out, Let's open https: // localhost: 4000/in your browser. ** X-Road Security Server management screen **.

Safari says "The connection is not private" and Chrome says "This connection does not protect your privacy", but I understand that I can move on.

On the login screen, log in with the environment variables PX_ADMINUI_USER and PX_ADMINUI_PASSWORD.

What is X-Road?

What on earth have you launched now? What is a Security Server?

Figure 1 Deployment view of X-Road (red line emphasized by the author)

The planetway/xroad-securityserver Docker Image written in docker-compose.yml is the software that corresponds to the blue box of Client Security Server and Service Security Server in the above figure.

X-Road information linkage means using the functions provided by the Service Information System in the organization called Service Provider from the Client Information System in the organization called Service Client.

The Security Server acts as a Forward Proxy from the perspective of the Client Information System and a Reverse Proxy from the perspective of the Service Information System. Security Server builds a secure tunnel that connects the Client Information System and the Service Information System over the Internet.

SOAP and REST protocols are spoken between the Client Information System and the Client Security Server, and between the Service Information System and the Service Security Server.

Let's try X-Road information linkage.

Activate certificate for authentication, register Security Server and register Subsystem

planetway/xroad-securityserver Docker Image automatically executes some setup steps when starting up Security Server, but there are still a few steps before information linkage = HTTP request is sent to Security Server. there is.

Activate the certificate for authentication.

Open https: // localhost: 4000/and log in. Click "KEYS AND CERTIFICATES"-> Click ">" to the left of "Token: softToken-0"-> Click "TEST of Planetway Intermediate L1 Organizations CA 2020 ..."-> Click "ACTIVATE" ..

Activated the certificate for authentication. Send us a Security Server registration request.

Press X to close the screen and click "KEYS AND CERTIFICATES"-> press the "Register" button.

Enter "127.0.0.1" and press the "ADD" button. You have now submitted a Security Server registration request.

The Central Server in Figure 1 manages the organizations that participate in X-Road and the security server catalogs operated by each organization. The Security Server registration request is a request to have this Security Server registered in the Central Server catalog.

Next, register the Subsystem. Click "CLIENTS"-> press the "Add Subsystem" button.

Enter "democlient" for "Subsystem Code" and press the "ADD SUB SYSTEM" button.

If you press "CLIENTS" and the following is displayed (if you see a green circle and "REGISTERED" in the Docker Demo Company (Owner) and democlient lines), Subsystem registration is complete.

The Client Information System information system belonging to the Service Client organization in Figure 1 has been registered with the name democlient.

Change the Security Server Connection Type to HTTP

It's about time.

HTTPS is used by default between the Client Information System and the Client Security Server. In this article, we'll change it to HTTP for brevity.

On the same management screen, click "CLIENTS"-> click on the word "democlient"-> click "INTERNAL SERVERS". Change "CONNECTION TYPE" to "HTTP" as shown below.

Send HTTP request to Security Server

For Service Providers, use the one provided by Planetway in advance for this article. Planetway offers an X-Road service called time that returns the current time as a demo.

Execute the curl command as follows.

% curl -v "http://localhost:8000/r1/JP-TEST/COM/0170368015672/demoprovider/time" -H "X-Road-Client: JP-TEST/COM/0170121212121/democlient"
* Connected to localhost (127.0.0.1) port 8000 (#0)
> GET /r1/JP-TEST/COM/0170368015672/demoprovider/time HTTP/1.1
> Host: localhost:8000
> User-Agent: curl/7.64.1
> Accept: */*
> X-Road-Client: JP-TEST/COM/0170121212121/democlient
>
< HTTP/1.1 200 OK
< Date: Wed, 13 Jan 2021 12:33:54 GMT
< Content-Type: text/plain;charset=utf-8
< x-road-id: JP-TEST-b3fcf843-4d50-4108-b25a-22b5993ad0c9
< x-road-client: JP-TEST/COM/0170121212121/democlient
< x-road-service: JP-TEST/COM/0170368015672/demoprovider/time
< x-road-request-id: f13d39d1-c5a7-4fc5-bd2f-ac002e2dc2e7
< x-road-request-hash: N02MYtDKDzpT1QN7uUQlgUa+I5Vu5ImpX1WKxj/fByjKCUITbWgAlySJwfSt0xQU1AzaPG0RiEqoONQBxXD0jQ==
< Content-Length: 41
<
{"now":"2021-01-13T12:33:54.692995982Z"}

Is displayed, it is successful!

We will unravel this curl command.

localhost: 8000 In my environment, Docker is running on Docker Desktop for macOS. In docker-compose.yml at the beginning of this article, there was -8000: 80 under ports. This forwards localhost: 8000 to port 80 of the Docker container. The Security Server in the Docker container is listening on port 80.

/ r1/JP-TEST/COM/0170368015672/demoprovider/time The protocol between the Information System and Security Server follows a protocol called X-Road: Message Protocol for REST. The path part of the URL is described as serviceId in the Message Protocol for REST document. r1 is the protocol version. JP-TEST is the ID of the X-Road instance. An instance of X-Road is a group that includes the entire box shown in Fig. 1, and includes a Governing Authority/operating organization and a group of organizations that cooperate information in the environment provided by the operating organization. JP-TEST is operated by Planetway. Others include EE (Estonia) and FI (Finland). COM indicates that the organization participating in X-Road is a legal entity. Others include GOV. 0170368015672 is the X-Road Member ID for Planetway. 0170121212121 is a test X-Road Member ID that can be used by Docker Image users. demoprovider is a Subsystem ID that represents Planetway's information system. time is the X-Road Service code.

The value in the header X-Road-Client: JP-TEST/COM/0170121212121/democlient represents the Client Information System.

Security Server also includes access control features. The time service has been set in advance so that it can be called from JP-TEST/COM/0170121212121/democlient.

time X-Road Service entity

The time service is implemented as Golang code as below.

package main

import (
	"encoding/json"
	"net/http"
	"os"
	"time"
)

func handler(w http.ResponseWriter, r *http.Request) {
	t := time.Now()

	enc := json.NewEncoder(w)
	err := enc.Encode(map[string]interface{}{
		"now": t,
	})
	if err != nil {
		http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
		return
	}
}

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	http.HandleFunc("/", handler)
	http.ListenAndServe(":"+port, nil)
}

It's an API server that returns ordinary JSON. Note that the first argument of http.HandleFunc is/. This is the Service Information System in Figure 1.

Here are some points that I find interesting.

1. Security Server is a simple tunnel when viewed from the Information System

The difference between the procedure of running this Golang server locally and sending an HTTP request with curl to the started server and the procedure of calling the time service provided by Planetway somewhere on the Internet is small. Only the X-Road-Client request header and the path part of the URL.

1. The security aspect of X-Road is invisible to the Information System

How does it compare to common external APIs? I can't see anything like a Bearer token or a client certificate. Authentication and authorization are hidden by the Security Server.

1. The curl request is sent to Security Server

All you need to know is the serviceId, which consists of the organization's ID and the service ID in it. You don't need to know the URL of the other party. The RPC layer is neatly placed on top of the Internet layer.

Summary

I launched the X-Road Security Server in Docker and ran a curl command to call a demo service that returns the time through it.

Continue