はじめに

X-Roadは、エストニアの政府機関や、政府機関と連携を行う企業(銀行など)の間で使われている情報連携を行うための技術です。

X-Roadはソースコードはgithub.com/nordic-institute/X-Roadにあるものの、Docker Imageやダウンロードしてすぐ動くパッケージがなかったので使ってみた系の記事があまりありませんでした。

最近、Planetway社でX-Roadを手軽に試せるDocker Imageを公開しました[hub.docker.com]。
この記事では、X-Roadを知らない方向けに、事前知識を端折りながらまずはX-Roadを使ってみることから始めます。

# full disclosure 私はPlanetway社の中の人です

docker-compose upでX-Road Security Serverを立ち上げる

Docker Imageが公開されているのです。
何はともあれローカルで立ち上げてみましょう。

作業用のディレクトリを作り、Docker Hubのドキュメントにある内容をコピーしてdocker-compose.ymlファイルを作成します。


% 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:

Docker Hubのドキュメントでは環境変数を...と省略しているところはとりあえず適当に埋めます。

PX_SS_CODEはX-Roadメンバー(X-Roadに参加する組織)の中のSecurity Serverを表すユニークな文字列です。ここからコピペする際には、ユニークな文字列に変更してください。

そしてdocker-compose upしてSecurity ServerとPostgreSQLをまとめて起動します。


% 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
...
# しばらく待つと
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"}

↑の最後の行が出てきたら、
https://localhost:4000/ をブラウザで開いてみしょう。
X-Road Security Serverの管理画面です。

Safariでは"接続はプライベートではありません", Chromeでは"この接続ではプライバシーが保護されません"と表示されますが、理解しているので先に進みます。

ログイン画面では環境変数のPX_ADMINUI_USERとPX_ADMINUI_PASSWORDでログインします。

X-Roadとは

今一体何を立ち上げたのでしょうか。
Security Serverとは何でしょうか。

図1 Deployment view of X-Road (赤い線は筆者による強調)

docker-compose.ymlに書いたplanetway/xroad-securityserver Docker Imageは、上図のClient Security Server, Service Security Serverの青い箱に当たるソフトウェアです。

X-Roadの情報連携とは、Service Clientという組織内のClient Information Systemから、Service Providerという組織内のService Information Systemが提供する機能を使うことを表します。

Security Serverは、Client Information Systemから見るとForward Proxyの役割を果たし、Service Information Systemから見るとReverse Proxyの役割を果たします。Security ServerはClient Information SystemとService Information Systemをインターネットを通してつなげるセキュアなトンネルを構築します。

Client Information SystemとClient Security Serverの間、そしてService Information SystemとService Security Serverの間は、SOAPとRESTプロトコルを話します。

X-Roadの情報連携をやってみましょう。

認証用証明書のActivate、Security Serverの登録とSubsystemの登録

planetway/xroad-securityserver Docker Imageは、Security Server立ち上げ時のセットアップ手順をいくつか自動的に実行しますが、情報連携を行う＝HTTPリクエストをSecurity Serverに送る、までにはまだいくつかステップがあります。

認証用証明書をActivateしましょう。

https://localhost:4000/ を開き、ログインします。
"KEYS AND CERTIFICATES" をクリック -> "Token: softToken-0"の左の ">" をクリック -> "TEST of Planetway Intermediate L1 Organizations CA 2020 ..." をクリック -> "ACTIVATE" をクリックします。

認証用証明書をActivateしました。
Security Serverの登録リクエストを送りましょう。

バツを押してその画面を閉じ、"KEYS AND CERTIFICATES" をクリック -> "Register" ボタンを押します。

"127.0.0.1"と入力し "ADD" ボタンを押します。
これでSecurity Serverの登録リクエストを送信したことになります。

図１のCentral Serverでは、X-Roadに参加する組織と、それぞれの組織が運用するSecurity Serverのカタログを管理しています。Security Serverの登録リクエストは、Central ServerのカタログにこのSecurity Serverを登録してもらうためのリクエストです。

次にSubsystemの登録を行います。
"CLIENTS" をクリック -> "Add Subsystem" ボタンを押します。

"Subsystem Code"には"democlient"と入力し、"ADD SUBSYSTEM"ボタンを押します。

"CLIENTS"を押し以下のように表示されていれば(Docker Demo Company (Owner)とdemoclientの行に緑の円と"REGISTERED"が表示されていれば)Subsystemの登録は完了です。

図1におけるService Client組織に所属するClient Information System情報システムをdemoclientと言う名前で登録しました。

Security ServerのConnection TypeをHTTPに変更する

もうそろそろです。

Client Information SystemとClient Security Serverの間は、デフォルトではHTTPSを使用します。この記事では簡略化するためHTTPに変更します。

同管理画面で、"CLIENTS" をクリック -> "democlient" の文字のところをクリック -> "INTERNAL SERVERS" をクリックします。下図のように、"CONNECTION TYPE"を"HTTP"に変更してください。

HTTPリクエストをSecurity Serverに送る

Service Provider側は、この記事では、予めPlanetway社が提供するものを利用しましょう。Planetway社では、現在時刻を返すtimeというX-Roadサービスをデモとして提供しています。

以下のようにcurlのコマンドを実行してください。


% 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"}

と表示されれば成功です！

このcurlコマンドを紐解いていきます。

localhost:8000 私の環境では、DockerはmacOS用のDocker Desktopで動作させています。この記事冒頭のdocker-compose.ymlではports以下に- 8000:80とありました。これはlocalhost:8000をDocker containerの80番ポートに転送します。Docker container内のSecurity Serverはポート80番でlistenしています。

/r1/JP-TEST/COM/0170368015672/demoprovider/time Information SystemとSecurity Serverの間のプロトコルは、X-Road: Message Protocol for RESTと言うプロトコルにしたがいます。URLのpath部分はMessage Protocol for REST文書の中でserviceIdとして記載があります。
r1はプロトコルのバージョン。
JP-TESTはX-RoadインスタンスのIDです。X-Roadのインスタンスとは、図1に表される箱全部を含んだまとまりで、あるGoverning Authority/運営機関と、運営機関が提供する環境で情報連携を行う組織群を含みます。JP-TESTはPlanetway社が運営機関を務めています。他にEE(エストニア), FI(フィンランド)などがあります。
COMはX-Roadに参加する組織が法人であることを表します。他にGOVなどがあります。
0170368015672はPlanetway社を表すX-Road Member IDです。0170121212121はDocker Imageの使用者が使えるテスト用のX-Road Member IDです。
demoproviderはPlanetway社の情報システムを表すSubsystem IDです。
timeはX-Road Serviceコードです。

X-Road-Client: JP-TEST/COM/0170121212121/democlient というヘッダの値は、Client Information Systemを表しています。

Security Serverはアクセスコントロールの機能も含みます。予めtimeサービスは、JP-TEST/COM/0170121212121/democlientから呼び出せるよう設定済みです。

time X-Road Serviceの実体

timeサービスは以下のようなGolangのコードとして実装しています。


package main

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

func handler(w http.ResponseWriter, r *http.Request) {
	w.Header().Add("Content-Type", "application/json")

	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)
}

普通のJSONを返すAPIサーバですね。http.HandleFuncの第一引数が/であることに注意。これが図1のService Information Systemに当たります。

いくつか私が面白いと思う点を書きます。

Security ServerがInformation Systemから見るとシンプルなトンネルであること

このGolangのサーバをローカルで実行し、立ち上がったサーバにcurlでHTTPリクエストを送る手順と、インターネットのどこかでPlanetway社が提供するtimeサービスを呼び出す手順の違いが小さいこと。X-Road-Clientリクエストヘッダ、URLのpath部分だけです。
X-Roadのセキュリティ面はInformation Systemには見えない

よくある外部APIと比較するとどうでしょう。Bearer tokenのようなものもクライアント証明書も何も見えません。認証や認可はSecurity Serverが隠蔽しています。
curlのリクエスト送り先はSecurity Server

知る必要があるのは、組織のID、その中のサービスIDからなるserviceIdだけです。相手のURLは知る必要がありません。インターネットのレイヤの上に綺麗にRPCのレイヤをのっけています。

まとめ

DockerでX-Road Security Serverを立ち上げ、それを通して時刻を返すデモサービスを呼び出すcurlコマンドを実行しました。

続く