2021-08-11-sprint-report-cw-32.md

title: Sprintwechsel KW32
tags: [sprint-report, roadmap-update]

Im Folgenden wollen wir euch ein kurzes Update bzgl. unseres Sprints geben. Hierbei wollen wir auf die Stories eingehen, die wir bearbeitet haben, sowie den Stand der noch offenen Stories durchgeben.

Falls relevant soll auch ein entsprechendes Update der Roadmap kommuniziert werden.

Dieses Format soll nun bei jedem Sprintwechsel veröffentlicht werden.

Stories

Umgesetzt

Finalisierung des Autorisierungskonzepts

Im Rahmen dieser Story wurden die begonnenen Arbeiten an der Umstellung der OAuth Autorisierung umgesetzt. Die FIT-Connect-Infrastruktur wurde gegen die neuen Tokens und Scopes getestet und die Dokumentation und API-Spec aktualisiert. Die Neuerungen der OAuth-Autorisierung lassen sich wie folgt zusammenfassen:

• Die Zugriffsberechtigung für Zustellpunkte basiert nun auf Scopes (manage:destination:<uuid> bzw. subscribe:destination:<uuid>) und nicht mehr auf der Identität des konkreten API-Client, der den Zustellpunkt initial erstellt hat. Dies erlaubt es, API-Clients flexibel auszutauschen, ohne hierfür den Zustellpunkt neu anzulegen oder auch mehreren API-Clients einen Zugriff auf einen Zustellpunkt zu ermöglichen.
• Neue Zustellpunkte können nur noch über das Self-Service-Portal angelegt werden. Die Verwaltung von Zustellpunkten ist weiterhin über die API möglich.
• Sendende Systeme können Access Tokens mit eingeschränkten Scopes abrufen, die nur für den Versand von Einreichungen an Zustellpunkte mit bestimmten Leistungen und Regionen gültig sind, um hiermit den Berechtigungsumfang eines Tokens einzuschränken. Wird von dieser Option kein Gebrauch gemacht, ist der Scope des Access Token für alle Regionen und Leistungen in Deutschland gültig.
  • Um diese spezifischen Berechtigungseinstellungen bei Access Tokens von sendenden Systemen zu ermöglichen, müssen in den Zustellpunkten nun die Leistungs-IDs (bspw. Angabe eines Leika Schlüssel) und die Region-IDs (aktuell ARS), die in diesem Zustellpunkt abgebildet werden, verpflichtend hinterlegt werden. Bei Leistungen, die nicht über den ARS abgebildet werden können oder keinen Ortsbezug haben, wird in dem Zustellpunkt als Regionsangabe lediglich DE angeben.

Die Nutzung von OAuth ist folgenden Artikeln beschrieben:

• Abruf von Access Tokens
• Scopes für sendende Systeme
• Scopes für empfangende Systeme

Wie Scopes bei der Registrierung und Verwaltung von API-Clients hinterlegt werden, wird in der Dokumentation zum Self-Service-Portal beschrieben, sobald dieses umgesetzt ist.

Endpunkt zur Abfrage der öffentlichen Informationen einer Destination

Bisher gab es keine Möglichkeit, dass ein sendendes System die öffentlichen Informationen eines Zustellpunktes abfragen konnte. Ein solcher Abruf ist bis zur Umsetzung der Routing-API notwendig, damit sendende Systeme die hinterlegten Informationen eines Zustellpunktes ermitteln können, da diese Informationen für eine fachlich und technisch korrekte Übermittlung zwingend erforderlich sind.

Daher wurde ein neuer Endpunkt umgesetzt, um die öffentlichen Informationen einer Destination abzurufen. Empfangende Systeme können für ihre eigenen Zustellpunkte zusätzlich auch die internen Informationen abrufen (technische Ansprechpersonen, Callback-Adresse).

Event Log der Submission

Zur Prüfbarkeit der Datenübermittlung erhält die Submission einen Event Log, der Security Event Tokens (SET) gemäß RFC 8417 enthält, die einzelne Ereignisse in der Datenübermittlung signiert dokumentieren. Ein Teil der Events werden vom Zustelldienst erzeugt, andere Events (bspw. im Kontext Akzeptanz oder Ablehnung der Submission) werden durch das empfangende System erzeugt. Der Event Log bzw. die SETs der einzelnen Events ersetzen das bisherige Statusmodell. Im Vergleich zum bisherigen Statusobjekt zeichnet sich ein SET durch eine Absicherung mittels Signatur, einen Zeitstempel und eine eindeutige Identifikation von Events aus. Aktuell werden SETs noch ohne einen Payload umgesetzt, der Events detaillierter beschreibt. Entsprechende Event-Payloads werden in zukünftigen Weiterentwicklung spezifiziert und umgesetzt.

Die Dokumentation kann hier eingesehen werden:

• Aufbau und Validierung des Event Log und der Event Tokens
• Abruf des Event Log für sendende Systeme
• Versendung des Event Log als Empfangsbestätigung durch empfangende Systeme

Schlüsselverwaltung des Zustelldienstes

Um die Urheberschaft und Integrität eines durch den Zustelldienst ausgestellen Security Event Tokens (SET) validieren zu können, ist es notwendig, die benutzten Schlüssel allen API-Clients zur Verfügung zu stellen. Daher stellt der Zustelldienst über einen /.well-known/jwks.json-Endpunkt alle Schlüssel dauerhaft bereit, damit eine Validierung von SETs auch noch Monate oder Jahre nach dem Einreichungsvorgang möglich ist. Näheres zur Validierung ist in der Dokumentation zu finden.

Implementierung des neuen Statusmodells

Mit der Einführung des Event Logs wurde auch ein neues Statusmodell für Einreichungen beschlossen. Dieses Statusmodell wurde im Zustelldienst implementiert und wird durch die Events des Eventlogs gesteuert.

schemas in submissionSchemas umbenennen

Im Rahmen der Qualitätsprüfungen der API wurde beschlossen, den Bezeichner schemas, der die referenzierten Fachdatenschemata in einer Destination bzw. im Metadatenschema beinhaltet, in submissionSchemas umzubenennen. Diese Umbenennung wurde in der API-Spec und Dokumentation angepasst.

Dokumentationsartikel "Versenden" im Überblick von Getting Started aufteilen

Um einen besseren Einstieg für Entwickler:innen von sendenden Systemen zu ermöglichen, wurden Inhalte aus dem Artikel "Überblick" in einen Artikel "Zustellpunkt ermitteln" überführt, der detaillierter beschreibt, wie die korrekte Destination-ID des gewünschten Zustellpunktes ermittelt werden kann und wie die Informationen eines Zustellpunkts für die Datenübermittlung zu nutzen sind.

Im Sprint nicht abgeschlossene Stories

Umsetzung des Self-Service-Portals

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

• Entwickler:innen und Verfahrensbetreiber:innen sollen ihre Software als API-Clients registrieren können und deren Berechtigungen (Scopes) verwalten können.
• Entwickler:innen und Verfahrensbetreiber:innen von empfangenden Systemen können über das Self-Service-Portal Zustellpunkte einrichten und verwalten.

Das Self-Service-Portal wird bis kommende Woche für die Nutzung für die öffentliche Test-API bereitgestellt. Interessierten Entwickler:innen stehen folgende Login-Möglichkeiten zur Verfügung:

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

XFall Schema: Erstellung eines Konzepts zur Ableitung eines JSON Schemas aus einem FIM Stammdatenschema

Um die Nutzung von FIM zur Datenübermittlung weiter zu vereinfachen, wurde eine JSON-Schema-Variante konzipiert. Das Konzept befindet aktuell noch in einem internen Review, wird aber demnächst zur Einsicht über das Gitlab der FITKO bereitgestellt.

---

Bei Fragen, Hinweisen oder Wünschen freuen wir uns gerne über Feedback. Dieses bitte über unseren Service Desk einkippen.