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
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 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.
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.
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.
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
.
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.
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.
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.
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.
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
Recommended Posts