Skip to content

Anbindung DVDV REST API

Warum machen wir das?

Damit der Routingdienst Informationen über einen Zustellpunkt beim DVDV abfragen kann, wird eine Anbindung des Zustelldienstes an die DVDV-API zum Übertragung von technischen Parametern des Zustellpunktes (Verschlüsselungszertifikat, Fachdatenschema, etc.) benötigt.

Relevante Links und Bemerkungen

Infos zur konkreten Umsetzung:

  • Der Zustelldienst authentifiziert sich mit einem OAuth-Token des FIT-Connect-OAuth-Servers beim DVDV-Microservice. Siehe #212
  • Die Signatur wird über die FIT-Connect--DVDV-Schnittstelle im Endpunkt PUT /destinations/<id> über den jws-signature-HTTP-Header übertragen.

Vorgaben zur Signaturanbringung

  • Bei der Signatur handelt es sich um eine Detached JSON Web Signature in der Compact Serialization (siehe https://datatracker.ietf.org/doc/html/rfc7515#section-3.1 und https://datatracker.ietf.org/doc/html/rfc7515#appendix-F).
  • Der Zustelldienst stellt zur Prüfung der Signatur ein JSON Web Key Set (JWKS) unter der URL https://<URL der Submission-API>/.well-known/jwks.json bereit, das öffentlichen Schlüssel enthält, der zur Prüfung der Signatur benötigt wird. Der passende Public Key kann anhand der Key-ID (kid) im Header der JSON Web Signature (JWS) ermittelt werden.
  • Vor der Signaturanbringung/-prüfung müssen alle semantisch unbedeutenden nicht-druckbaren Zeichen (Leerzeichen, Tabs, Line Feed \n, Carriage Return \r) vor und nach den strukturierenden Zeichen ([, {, ], }, :, ,) aus dem JSON-Payload entfernt werden.
  • Vor der Signaturanbringung/-prüfung müssen die Attribute des JSON-Objekts in alphabetischer Reihenfolge sortiert werden.

Entscheidungen

  • Hinterlegt der Zustelldienst in der submissionUrl eine URL mit Versionsangabe oder ohne (https://submission-api-testing.fit-connect.fitko.dev/v1/ vs https://submission-api-testing.fit-connect.fitko.dev/)?
    • Vorteil mit Versionsangabe: Einfachheit
    • Nachteil mit Versionsangabe: Es kann nur eine Version der API verlinkt werden
    • Vorteil ohne Versionsangabe: API-Clients können die von ihnen unterstützen Versionen der API selbst durchprobieren und anhand des vom Zustelldienst zurückgelieferten HTTP-Status-Code auto-detecten, welche Versionen der Zustelldienst unterstützt
    • Routingdienst-Team über Entscheidung informieren!
  • Entscheidung: ohne

Referenzen

Akzeptanzkriterien

  1. Der Zustelldienst erstellt und überträgt eine Signatur der Daten
  2. Detached JWS: Damit detached Signaturen weiterhin prüfbar sind, müssen Whitespaces und Zeilenumbrüche aus den Payloads entfernt werden und ggf. die Reihenfolge der Atttribute vereinheitlicht (sortiet) werden.
  3. Die submissionUrl wird ohne Versionsangabe im DVDV hinterlegt (https://submission-api-testing.fit-connect.fitko.dev/ nicht https://submission-api-testing.fit-connect.fitko.dev/v1/.
  4. Die Vorgaben zur Signaturanbringung (s.o.) wurden beachtet.
  5. Routingdienst-Team wurde durch @Marco_Holz über Entscheidung (s. o.) informiert. -> https://git.fitko.de/fit-connect/routingdienst/-/issues/10#note_16442

Durchführungsplan

  • Einbauen von JobRunr
  • Signatur im Zustelldienst erstellen
  • DVDV-Service schreiben
Edited by Alexander Hoose