[Epic] Bidirektionale Kommunikation im Java & .NET-SDK

Warum?

Voraussetzung für dieses Epic ist die Fertigstellung des ~"Epic::Rückkanal" (Bidirektionale Kommunikation zw. Onlinedienst und Fachverfahren) -> Möglichkeit des Fachverfahrenauf Anträge antworten zu können und dann als Onlinedienst diese Antwort zu verarbeiten um ggf. erneut eine Einreichung zu einem bestehenden Vorgang (Case-ID) zu versenden.

Mit der bidirektionalen Kommunikation wurden die Kommunikationsmöglichkeiten von FIT-Connect an der Submission API erweitert. Die Nutzung der neuen Funktionalitäten dieser API soll für Anbindende einfach über ein SDK ermöglicht werden - sowohl für JAVA, .NET.

Relevante Links und Bemerkungen

API-Spezifikation: https://docs.fitko.de/fit-connect/docs/apis/submission-api/?version=1.3.0-rc3
Metadatensatz: https://schema.fitko.de/fit-connect/metadata/1.2.0-rc1/
Ablauf aus #42 (closed)

sequenceDiagram
autonumber
loop Bidirektionale Kommunikation
opt Falls noch kein Key vorhanden
Sender->>Sender: Pro Vorgang (bzw. pro Antragsteller:in) einen Encryption Key für Rückkanal generieren
end
Sender->>Sender: Metadatensatz mit Encryption Key und Angabe zum Prozesstandard generieren
Sender->>Sender: Submission Bestandteile mit dem Public Key der Destination verschlüsseln
alt Falls ein neuer Case angelegt wird
Sender->>Zustelldienst: Submission mit Rückkanaloption anlegen
Zustelldienst->>Zustelldienst: Bidirektionalen Vorgang anlegen
else Falls ein bestehender Case genutzt wird
Sender->>Zustelldienst: Submission für ein bestehenden Case anlegen
end
Sender->>Zustelldienst: Submission übersenden
Zustelldienst->>Subscriber: Einreichung abrufen
Subscriber->>Subscriber: Security Event Token für Accept / Rejectgenerieren
Subscriber->>Zustelldienst: Security Event Token übermitteln
Subscriber->>Subscriber: Prozessstandard und Encryption Key aus dem Metadatenschema entnehmen
Subscriber->>Subscriber: Reply Bestandteile mit dem Encryption Key verschlüsseln
Subscriber->>Zustelldienst: Reply anlegen und übersenden
Zustelldienst->>Sender: Reply abrufen
Sender->>Zustelldienst: Accept oder Reject senden
Zustelldienst->>Zustelldienst: Security Event Token für Accept / Reject generieren
end

Link auf dem Karate-Test (kommt noch von Christoph)
Temporäre BiDiKO DEV Umgebung (aus #1246 (closed))
- Self-Service-Portal: https://portal.auth-bidiko.fit-connect.dev/
- OAuth-Server: https://auth-bidiko.fit-connect.dev/
- Submission API: https://submission-api-bidiko.fit-connect.dev/v1/info

Akzeptanzkriterien und Anwendungsfälle

Übergreifende Akzeptanzkriterien:

Alle Endpunkte der aktualisierten Submission-API werden über die SDKs nutzbar gemäß der Anwendungsfälle genutzt

Methodensignaturen sind über alle Programmiersprachen (angemessen) gleich
Alle Funktionalitäten des SDKs sind in der Dokumentation integriert mit entsprechenden Code-Beispielen
Video zur Nutzung des SDKs wurde bereitgestellt
Kommunikationsmaßnahmen begleitend zur Veröffentlichung der Test- und Produktiv-nutzbaren Version wurden angestoßen

Stories zu dem Epic

offene Fragen:

AK1.1 @Marco_Holz können wir für die Generierung der ~~Zertifikate~~ Schlüsselpaare auf der Generierung der Testzertifikate aufsetzen?
- Anmerkung @Marco_Holz: Grundsätzlich ja. Hilfreich wäre sicherlich, wenn wir uns für das kid-Atrribut eine Struktur überlegen, anhand der erkennbar ist, dass es sich um einen von einem Onlinedienst erstellen Key handelt. Initialer Vorschlag: "kid": "reply-key:{caseId}"?
AK1.1 @Marco_Holz Welche Gültigkeitsdauer des Zertifikats wäre angemessen? 10 Jahre ok?
- Für den Rückkanal kommen keine X509-Zertifakte aus der V-PKI zum Einsatz, sondern ad-hoc generierte Schlüsselpaare (sog. ephemeral keys). Dazu brauchen wir also keine Zertifikate im x5c-Feld, aus denen die Schlüssel abgeleitet sind, sondern können direkt JSON Web Keys generieren. JWKs enthalten keinen Gültigkeitszeitraum.
AK1.2, AK1.5, AK2.3 @Marco_Holz Feld Prozessstandard - ist es auch ein Fachdatenschema / bzw. äquivalentes und muss dann das Payload ähnlich wie bei der Submission validiert werden?
- Zum Unterschied zw. Fachdatenschema und Prozessstandard, siehe https://docs.fitko.de/fit-connect/docs/getting-started/submission/data#unterscheidung-fachdatenschema--prozessstandard. Die Angabe eines Prozessstandards sagt aus, dass alle Fachdatenschemata aus diesem Prozesstandard unterstützt werden. Hier müssten wir uns noch einmal Gedanken machen, ob und wenn ja, wie wir eine Schema-Validierung basierend auf der Angabe eines Prozesstandards vornehmen können.
AK3.3 @Marco_Holz sind in GET /v1/cases/{caseId}/events sowohl die Events der Submissions als auch der Replies enthalten? Aktuell geben die SDKs nur den letzten Status zurück. Sofern mehrere Submissions & Replies enthalten sind wird das etwas kompliziert, daher wäre der Vorschlag alle auszugeben und entsprechende Filtermögichkeiten einzurichten.
- Wir brauchen je eine Methode, um den Zustand einer Submission und den Zustand eines Replys ermitteln zu können. Im SDKs könnten wir das zunächst so umsetzen, dass die Events vor der Ermittlung des Zustands nach submissionI oder replyId gefiltert werden. Zukünftig wäre auch eine Filterung direkt am API-Endpunkt denkbar, z.B. so: GET /v1/cases/{caseId}/events?submissionId=dd5a7c58-9867-49b2-ac60-6b60b749bd57
Sollen für die Replies dieselben/ähnliche Prüfungen wie für die Submissions nach Docs stattfinden?

Anforderungen zur Verschlüsselung

Ist-Zustand (für Einreichungen)

Sender verschlüsselt eine Submission (bzw. deren Bestandteile) mit dem Public Key des Subscribers. Zertifikat aus Verwaltungs-PKI liegt pro Subscriber vor.

Sender können auch von externen Benutzern betrieben werden. Diese haben keine Zertifikate aus der Verwaltungs-PKI.

Sender übergibt beim Einreichen einen (optionalen) Public-Key mit, mit dem die Antworten verschlüsselt werden können:

Bei Antwort über Email per optionalem PGP-Key
Bei Antwort über FIT-Connect ein JSON Web Key (diesem liegt kein Zertifikat zugrunde)

Soll-Zustand

Für bidirektionale Kommunikation muss der Public-Key (im Meta-Datensatz durch den Sender) zwingend vorgegeben werden. Das kann nur im SDK bei der Einreichung geprüft und ggf. zurückgewiesen werden.

Edited Nov 06, 2023 by Wojciech Gdaniec