2021-08-23-sprint-report-cw-34.md

title: Sprintwechsel KW34
tags: [sprint-report]

Im Folgenden wollen wir euch wieder ein kurzes Update zum vergangenen Sprint geben. Hierbei wollen wir auf die Stories eingehen, die wir bearbeitet haben, sowie den Stand der noch offenen Stories durchgeben.

Stories

Umgesetzt

Generierung von JWKs ohne Zertifikatskette

Zur Vereinfachung von Anbindungstests haben wir ein Tool zur Generierung von Test-Schlüsselpaaren ohne Zertifikatskette erstellt.

Umsetzung des Self-Service-Portals

Das Self-Service Portal erfüllt in der ersten MVP-Ausbaustufe zwei Funktionen:

• Entwickler:innen und Verfahrensbetreiber:innen sollen ihre Software als API-Clients registrieren und deren Berechtigungen (Scopes) verwalten können. Die Anmeldung im Self-Service-Portal und die Registrierung von API-Clients ist im Artikel Accountregistrierung und Client-Verwaltung beschrieben.
• Entwickler:innen und Verfahrensbetreiber:innen von empfangenden Systemen können über das Self-Service-Portal Zustellpunkte einrichten und verwalten. Das Anlegen von Zustellpunkten für empfangende Systeme ist im Artikel Zustellpunkt anlegen beschrieben.

Interessierten Entwickler:innen stehen folgende Login-Möglichkeiten zur Verfügung:

• Login mit einem Account des FITKO-Gitlab (Account muss bei der FITKO angefragt werden)
• Login mit einem Github.com- oder Gitlab.com-Account

Mehrere Regionen pro Service

Durch die Nutzung des regions-Arrays (statt bisher region-Attributs) können mehrere Regionen pro Verwaltungsleistung angegeben werden. Siehe Zustellpunkt ermitteln.

Alle abholbereiten Einreichungen auflisten / abrufen

Wenn im Zustellpunkt eine Callback-URL hinterlegt ist, kann der Zustelldienst empfangende Systeme direkt via Callback informieren, sobald eine neue Einreichung eingeht. Empfangende Systeme können nun zusätzlich durch Polling, d.h. regelmäßiges Abfragen des Endpunktes GET /submissions prüfen, ob neue Einreichungen zur Abholen bereitstehen. Dies wird aus Performancegründen jedoch nicht empfohlen. Der Endpunkt kann zu Testzwecken als Alternative zu Callbacks genutzt werden oder, falls aus technischen Gründen die Nutzung eines Callbacks im Produktivbetrieb nicht möglich ist (bspw. Security Policies im RZ).

Die Nutzung des Endpunkts ist im Artikel Vorhandensein neuer Einreichungen prüfen beschrieben.

Event Logs

Zur Prüfbarkeit der Datenübermittlung und Empfangsbestätigung von Einreichungen erhält jede Submission einen Event Log, das Security Event Tokens (SET) gemäß RFC 8417 speichert. Manche der Events werden vom Zustelldienst erzeugt, manche werden extern über die API zugeliefert. Die Hintergründe sind im Artikel Event Log beschrieben. Das Abfragen des Status ist im Artikel Status abfragen beschrieben. Wie empfangende Systeme einen Security Event Tokens (SET) erzeugen und über die API bereitstellen können, ist im Artikel Empfangsbestätigung beschrieben.

Hinweis: Der Mechanismus zum Abrufen von kryptografischen Schlüsseln des empfangenden Systems wird sich bis zur Veröffentlichung der finalen API-Spezifikation noch einmal ändern.

Typ other des Identifikationsnachweises entfernt

Der bisherige Wert other als Typ einer AuthenticationInformation wurde im Metadatenschema entfernt, da er nicht besonders aussagekräftig ist und zur Bestimmung des Authentifizierungsschemas nicht ausreicht. Unser Ziel mit FIT-Connect ist, möglichst einheitliche Verfahren zur Authentifizierung zu unterstützen und zu dokumentieren. Daher werden wir diese bei zukünftigen Anforderungen hinsichtlich neu zu schaffender Authentifizierungschemata explizit inkl. einer ausführlichen Dokumentation zu deren Nutzung aufnehmen. Kommen Sie bei Bedarf gerne auf uns zu!

Diverse Verbesserungen der Dokumentation

• In der Dokumentation wurden die Bezeichnungen "FIT-Connect API", "Einreichungs-API" etc. zu "Submission API" vereinheitlicht. Künftig werden wir nur noch von Submission API sprechen, wenn die Schnittstelle des Zustelldienstes zur Übermittlung von Einreichungen gemeint ist.
• Der Artikel Zustellpunkt ermitteln wurde aktualisiert.
• Neu: Dokumentation zur Nutzung von Fachdatenschema für Sender
• Neu: Dokumentation zur Nutzung von Fachdatenschema für Empfänger
• Der Artikel Einreichung herunterladen wurde auf den neusten Stand der API aktualisiert.

Im Sprint nicht abgeschlossene Stories

Schlüsselverwaltung eines Zustellpunktes

Um zu vereinfachen, wie öffentliche kryptographische Schlüssel über die API bereitgestellt und heruntergeladen werden können, werden die neuen Endpunkte GET/PUT /destinations/{destinationId}/keys/{keyId} geschaffen. Wie oben beschrieben, wird sich dabei auch der Mechanismus zum Abrufen von kryptografischen Schlüsseln eines Zustellpuntes bis zur Veröffentlichung der finalen API-Spezifikation noch einmal ändern.

Ausblick: Weitere anstehende Änderungen bis zur finalen Schnittstelle {#ausblick}

Neben einigen internen Arbeiten werden wir bis zur Veröffentlichung der finalen Schnittstelle einige weitere Änderungen vornehmen. Mit Blick auf ggf. notwendige Anpassungen der Schnittstellenanbindung sind hierbei insb. die folgenden anstehenden Aspekte relevant:

• Weitere Verbesserungen im Self-Service-Portal: Der aktuelle MVP des Self-Service-Portals wird hinsichtlich Benutzbarkeit (UX) und Design weiterentwickelt werden.
• Das im Endpunkt GET /submissions/{submissionId} enthaltene Attribut announcedContentStructure wird entfernt. Die Liste der Anlagen ist bereits im Attribut attachments enthalten.
• Der im Metadatenschema genutzte IdenfitcationReport soll versioniert werden.
• Für die Endpunkte GET /destinations, GET /submissions und GET /submissions/{submissionId}/events wird eine Pagination umgesetzt.
• Umsetzung von Best-Practices für Callbacks: Zur Erhöhung der Sicherheit von Callbacks werden wir einheitliche Sicherheitsvorgaben für die Callback-Nutzung definieren, dokumentieren und in der API umsetzen. Dabei werden sich auch die Schnittstelle zur Konfiguration von Callbacks sowie die Vorgaben zur Prüfung von Callbacks noch einmal ändern. Auch sendende Systeme sollen zukünftig via Callback über Statusänderungen benachricht werden.
• In der Testumgebung können zu Testzwecken selbst-generierte kryptographische Schlüsselpaare ohne Absicherung über die Verwaltungs-PKI genutzt werden. Dies wird in der Produktivumgebung nicht mehr der Fall sein. Wir werden entsprechende Vorgaben zur Prüfung der Zertifikatskette sowie die nötigen Schritte zur Ableitung von JSON Web Keys (JWKs) aus Zertifikaten beschreiben.
• Eine Methode zum Deaktivieren/Löschen von Zustellpunkten wird noch ergänzt.
• Vorgaben zur Maximalgröße von Einreichungen werden noch ergänzt.
• Die Möglichkeiten zur Angabe von Rückkanaloptionen werden noch einmal überarbeitet und ausgebaut.
• Ein Konzept zur Versionierung der API und des Metadatenschema befindet sich gerade in der Entwicklung und wird Handreichungen zum Umgang mit zukünftigen API-Änderungen bieten.

Ein Überblick über alle anstehenden Änderungen der Submission API gibt der Issue-Tracker des Submission API-Repositories. Auch an der Dokumentation werden wir kontinuierlich Arbeiten. Die uns bereits bekannten Verbesserungspotenziale finden sich im Issue-Tracker des Dokumentations-Repositories.

---

Bei sonstigen Fragen, Hinweisen oder Wünschen freuen wir uns über Feedback über unseren Service Desk oder per Mail an fit-connect <ät> fitko.de.