Syndication-Zertifikat einrichten

Ontoserver ist in der Lage, Inhalte auf dem Server an andere Server zu verteilen. Dieser Prozess wird als Syndication bezeichnet, mehr erfahren Sie in der Dokumentation des Ontoserver.

Zugriffsschutz mittels mTLS

Die durch die SU-TermServ gehostete Instanz ist mittels Mutual-TLS gesichert. Dies bedeutet, dass bei jedem Zugriff auf den Endpunkt ein beidseitiger Zertifikatsaustausch stattfindet, somit ist auch auf Ihrer Seite ein entsprechendes Zertifikat einzurichten und bei jedem Verbindungsaufbau zu präsentieren ist:

Cloudflare: Was ist mutual TLS (mTLS)?

Als Grundlage für die Einrichtung ist natürlich ein entsprechendes Zertifikat zu beantragen. Hierzu sei auf den entprechenden FAQ-Eintrag verwiesen.

Einrichtung Ontoserver

Die Einstellungen von Ontoserver sind über Umgebungsvariablen im Container festzulegen. Es sind folgende Einstellungen zu treffen:

1. Das Zertifikat muss dem Dienst bekannt gemacht werden, da auch Syndication nur mit einem entsprechenden Zertifikat abgerufen werden kann.
2. Ontoserver muss auf die korrekte URL für den Syndication-Feed eingestellt werden
3. ggf. ist es erwünscht, dass Ihre Instanz wiederum einen Syndication-Feed anbietet, in dem auch die Ressourcen des Upstreams distributiert werden.

Zertifikat-Bereitstellung

Zuerst ist sicherzustellen, dass das Zertifikat im PKCS12-Format innerhalb des Ontoserver-Containers verfügbar ist. Hierbei ist es sinnvoll, das legacy-Format für PKCS12 zu verwenden (die Einträge sind mit 3TDEA statt mit AES256 verschlüsselt), weil die AES-Verschlüsselung nicht durch alle Betriebssysteme unterstützt wird. In unseren Tests ist aber auch die mittlerweile durch OpenSSL standardmäßige AES-Verschlüsselung mit der Java-Runtime des Ontoservers kompatibel.

Falls Sie eine Zertifikats-Chain im PEM-Format und den dazugehörigen privaten Schlüssel vorliegen haben, können Sie diese mit OpenSSL in der Konsole in das PKCS12-Format konvertieren, z.B mit:

openssl pkcs12 -in your-chain.pem -inkey your-private.key -out syndication.p12 -export

Hierbei ist ein Passwort einzugeben, dieses sollte nicht leer gelassen werden, damit es bei der Übergabe an Ontoserver nicht zu Problemen kommt. Falls Sie bereits ein Zertifikat im PKCS12-Format haben, aber noch kein Passwort vergeben ist, empfehlen wir das graphische Tool Keystore Explorer.

Falls das legacy-Format gewünscht ist, kann der Parameter -legacy an den obigen Befehl angefügt werden.

Die entstehende Datei ist dann innerhalb des Ontoserver-Containers zur Verfügung zu stellen, z.B. innerhalb eines Bind Mounts (eine exemplarische docker-compose.yaml-Datei ist unten verfügbar).

Nun ist das Zertifikat dem Ontoserver-Prozess zur Verfügung zu stellen, dies erfolgt über Java-Optionen, die innerhalb einer Umgebungsvariable zu setzen sind.

Exemplarisch für einen Minimal-Server ist folgende Option zu setzen:

JAVA_OPTS=-Xmx4G -Dspring.datasource.url=jdbc:postgresql://onto-db/postgres -Djavax.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=/syndication.p12 -Djavax.net.ssl.keyStorePassword=password

In dieser Zeile werden auch weitere Optionen, konkret der zugewiesene Arbeitsspeicher (hier maximal 4 Gigabyte, sodass ein manuelles Indizieren von SNOMED CT durch Ontoserver abgelehnt werden würde, und SNOMED CT nur via Syndication konsumiert werden kann) und die JDBC-URL zur PostgreSQL-Datenbank (hier unter dem Docker-Hostnamen onto-db), angepasst, passen Sie diese Parameter natürlich entsprechend an.

Über die drei Optionen Djavax.ssl.keyStoreType, -Djavax.net.ssl.keyStore und Djavax.net.ssl.keyStorePassword wird bei einem HTTP-Request aus Ontoserver heraus das entsprechende Zertifikat präsentiert, sodass ein Zugriff auf den Syndication-Feed, die Binär-Indizes für SNOMED CT und LOINC, sowie die FHIR-API für das Konsumieren von FHIR-Ressourcen über Syndication nun möglich sein sollte.

Einrichtung Syndication

Als zweiter Schritt ist Ontoserver nun an den Syndication-Feed des Upstreams anzuschließen:

atom.syndication.feedLocation=https://ontoserver.mii-termserv.de/synd/syndication.xml

Hiermit ist die minimal notwendige Konfiguration nun abgeschlossen.

Fein-Anpassung Syndication

Falls gewünscht, können noch weitere Optionen für Syndication getroffen werden, z.B. kann Ontoserver mehrere Syndication-Quellen gleichzeitig konsumieren und dann zusammengeführt als eine weitere XML-Datei bereitstellen. Für die entsprechenden Optionen sei auf die Ontoserver-Dokumentation verwiesen.

Interessante Optionen könnten unter Anderem folgende sein:

• atom.syndication.publish.enabled - hiermit wird Ihr Server wiederum zu einem Syndication-Upstream (true/false)
• atom.syndication.publish.fhir.enabled - sollen alle FHIR-Ressourcen distributiert werden (true), nur markierte (selected), oder keine (false)?
• atom.syndication.publish.index.enabled - dito für SNOMED CT und LOINC, die als Binär-Indizes distributiert werden (true/selected/false).
• atom.syndication.republishUpstreamEntries - so werden alle Ressourcen unseres Upstream-Feeds in Ihrem Feed inkludiert, nicht nur eigene Ressourcen.
• ontoserver.synd.base - Hiermit können Sie (in Kombination mit ontoserver.fhir.base) die URLs, die in Ihrem Syndication-Feed verwendet wird, anpassen
• atom.syndication.publish.feedTitle - Den Namen Ihres eigenen Syndication-Feeds (ein beliebiger String)
• atom.syndication.exludeXml - kann gut auf gesetzt werden, damit der Feed kleiner wird
• atom.syndication.disableChecksums - dito

Funktionstest

Zum Verwenden der Syndication ist das Tool “Ontocommand” von CSIRO sehr hilfreich.

Wenn Sie https://ontoserver.csiro.au/ui aufrufen, sollte eine Seite erscheinen, in der Sie den Endpunkt Ihres Servers eintragen können (für dieses Beispiel zum Beispiel einfach http://localhost:8080/fhir). Es sei darauf hingewiesen, dass Ontocommand aus Ihrem Browser direkt mit den Diensten des Ontoservers spricht, sodass Sie auf Ihrem System Sorge für die entsprechenden CORS-Header tragen müssen.

Klicken Sie nun auf Syndication in der linken Navigation, sollte Ihr Server automatisch den Feed laden und anzeigen:

Der Feed beim Aufruf von Ontocommand

Sie können nun sowohl Binär-Indizes für SNOMED CT und LOINC als auch FHIR-Ressourcen durch den entsprechenden Button in Ihren Server laden:

Binär-Indizes im Feed

FHIR-CodeSystem-Ressourcen im Feed

Beispielhafte Konfigurationsdateien

docker-compose.yaml (Minimalbeispiel)

services:
  onto-db:
    image: postgres:12
    container_name: onto-db
    volumes:
      - ./data/pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust

  ontoserver:
    image: quay.io/aehrc/ontoserver:ctsa-6
    container_name: ontoserver
    ports:
      - 8080:8080
    depends_on:
      onto-db:
        condition: service_healthy
    env_file:
      - ./.ontoserver.env
    volumes:
      - ./data/onto:/var/onto
      - ./syndication-certificate.p12:/syndication.p12

.ontoserver.env

ONTOSERVER_INSECURE=true
JAVA_OPTS=-Xmx4G -Dspring.datasource.url=jdbc:postgresql://onto-db/postgres -Djavax.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=/syndication.p12 -Djavax.net.ssl.keyStorePassword=password
atom.syndication.feedLocation=https://ontoserver-ballot.mii-termserv.de/synd/syndication.xml
ontoserver.security.enabled=false
atom.syndication.publish.enabled=true
atom.syndication.publish.feedTitle=Tester for Ontoserver Syndication Redistribution