Im Folgenden wollen wir euch ein kurzes Update bzgl. unseres Sprints geben.
Im Folgenden wollen wir euch ein kurzes Update bzgl. unseres Sprints geben.
...
@@ -17,61 +16,68 @@ Dieses Format soll nun bei jedem Sprintwechsel veröffentlicht werden.
...
@@ -17,61 +16,68 @@ Dieses Format soll nun bei jedem Sprintwechsel veröffentlicht werden.
#### Finalisierung des Autorisierungskonzepts
#### Finalisierung des Autorisierungskonzepts
Im Rahmen dieser Story wurden begonnenen Arbeiten an Umstellung der OAuth Autorisierung für die API Zugriffe umgesetzt. Hierzu wurde Software gegen die neuen Tokens und Scopes getestet und die Dokumentation und API Spec aktualisiert. Wesentliche Neuerungen der neuen OAuth Autorisierung:
Im Rahmen dieser Story wurden die begonnenen Arbeiten an 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 neuen OAuth Autorisierung lassen sich wie folgt zusammenfassen:
- Zugriff auf die Verwaltung von Zustellpunkten und Abruf von Einreichungen basiert nun auf Scopes und nicht mehr auf dem konkreten Client, der den Zustellpunkt erstellt hat. Dies erlaubt es, flexibel API-Clients auszutauschen, ohne hierfür den Zustellpunkt neu anzulegen oder auch den Zugriff auf Zustellpunkte für mehrere API-Clients zu ermöglichen.
-Die Zugriffsberechtigung für Zustellpunkte basiert nun auf Scopes (`manage:destination:<uuid>` bzw. `subscribe:destination:<uuid>`) und nicht mehr auf dem 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 mehrere API-Clients einen Zugriff auf den gleichen Zustellpunkt zu ermöglichen.
- Neue Zustellpunkte können nur noch durch das Self-Service-Portal erstellt werden. Die Verwaltung von Zustellpunkten ist jedoch weiterhin über die API möglich.
- Neue Zustellpunkte können nur noch durch das Self-Service-Portal erstellt werden. Die Verwaltung von Zustellpunkten ist jedoch weiterhin über die API möglich.
- Sendende Systeme können Access Token mit Scopes abrufen, die nur für Zustellpunkte mit bestimmten Leistungen und Regionen gültig sind, um hiermit den Berechtigungsumfang weiter 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.
- Sendende Systeme können Access Token mit eingeschränkten Scopes abrufen, die nur für Zustellpunkte mit bestimmten Leistungen und Regionen gültig sind, um hiermit den Berechtigungsumfang eines Tokens weiter 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 Berechtigungen bei Access Tokens von sendenden Systemen zu ermöglichen, müssen nun in den Zustellpunkten die Leistungs-IDs (bspw. Angabe eines Leika Schlüssel) und die Region-ID (aktuell ARS) verpflichtend angegeben werden, die in diesem Zustellpunkt abgebildet werden. Leistungen, die nicht über den ARS abgebildet werden oder keinen Ortsbezug haben, werden in dem Zustellpunkt mit DE angeben werden.
- 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 beschrieben:
Die Nutzung von OAuth ist folgenden Artikeln beschrieben:
- Scopes für sendende Systeme: https://docs.fitko.de/fit-connect/docs/details/authentication/scopes-sender
- Scopes für sendende Systeme: https://docs.fitko.de/fit-connect/docs/details/authentication/scopes-sender
- Scopes für empfangende Systeme: https://docs.fitko.de/fit-connect/docs/details/authentication/scopes-subscriber
- Scopes für empfangende Systeme: https://docs.fitko.de/fit-connect/docs/details/authentication/scopes-subscriber
Wie Scopes bei der Registierung und Verwaltung von API-Clients hinterlegt werden, wird in der Dokumentation zum Self-Service-Portal beschrieben, sobald dieses umgesetzt ist.
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
#### Endpunkt zur Abfrage der öffentlichen Informationen einer Destination
Aktuell gibt es keine Möglichkeit, dass ein sendendes System einen Zustellpunkt und dessen öffentliche Informationen abfragen kann. Ein solcher Abruf ist bis zur Umsetzung der Routing API zwingend notwendig, damit sendende Systeme Informationen über Destinations ermitteln können, die für eine fachlich und technische korrekte Übermittlung zwingend erforderlich sind (insbesondere Fachschemareferenzen und Keys für die Verschlüsselung der Einreichung).
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 zwingend notwendig, damit sendende Systeme die hinterlegten Informationen eines Zustellpunktes ermitteln können, da diese Informationen für eine fachlich und technische korrekte Übermittlung zwingend erforderlich sind.
Daher wurde ein neuer Endpunkt umgesetzt, der es sendenden Systemen erlaubt, für eine konkrete Destination die öffentlichen Informationen abzurufen. Empfangende Systeme können für ihre eigenen Destination (bspw. mit dem manage:destination:<id>) weiterhin alle Informationen einer Destination abrufen. Der spezifizierte Endpunkt kann hier eingesehen werden: https://docs.fitko.de/fit-connect/docs/apis/delivery-service#get-/destinations
Daher wurde ein neuer Endpunkt umgesetzt, um die öffentlichen Informationen einer Destination abzurufen. Empfangende Systeme können für ihre eigenen Zustellpunkt (bspw. mit dem Scope manage:destination:<id>) zusätzlich auch die internen Informationen abrufen. Der spezifizierte Endpunkt kann hier eingesehen werden: https://docs.fitko.de/fit-connect/docs/apis/delivery-service#get-/destinations
#### Event Log der Submission
#### Event Log der Submission
Zur Prüfbarkeit der Datenübermittlung erhält die Submission ein Event Log, das Security Event Token (SET) gemäß RFC 8417 und dem Dokument Event Log speichert. Ein Teil der Events werden vom Zustelldienst erzeugt, andere Events 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 der SET durch eine Integritätssicherung durch eine Signatur, Zeitstempel und eine eindeutige Identifikation von Events. Aktuell werden SETs noch ohne einen Payload umgesetzt, der die Events detailierter beschreibt. Entsprechende Payloads werden in zukünftigen Weiterentwicklung spezifiziert und umgesetzt.
Zur Prüfbarkeit der Datenübermittlung erhält die Submission ein Event Log, das Security Event Token (SET) gemäß RFC 8417 und dem Dokument Event Log speichert. 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 Integritätssicherung 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: https://docs.fitko.de/fit-connect/docs/getting-started/event-log
- Abruf des Event Log für sendende Systeme: https://docs.fitko.de/fit-connect/docs/getting-started/sending/query-status
- Versendung des Event Log als Empfangsbestätigung durch empfangende Systeme: https://docs.fitko.de/fit-connect/docs/getting-started/receiving/process-and-acknowledge
#### Schlüsselverwaltung des Zustelldienstes
#### Schlüsselverwaltung des Zustelldienstes
Um Security Event Tokens (SET) des Zustelldienstes eigenständig hinsichtlich der Signatur zu valdieren, ist es notwendig, diese Schlüssel allen API-Clients zur Verfügung zu stellen. Daher wird 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 hierzu hier: https://docs.fitko.de/fit-connect/docs/getting-started/event-log#signaturpr%C3%BCfung-eines-vom-zustelldienst-ausgestellten-set
Um die Integrität eines Security Event Tokens (SET) des Zustelldienstes 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 wird hier beschrieben: https://docs.fitko.de/fit-connect/docs/getting-started/event-log#signaturpr%C3%BCfung-eines-vom-zustelldienst-ausgestellten-set
#### Implementierung des neuen Statusmodells
#### Implementierung des neuen Statusmodells
Mit der Einführung des Eventslogs 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
#### schemas` in `submissionSchemas` umbenennen
Im Rahmen der Qualitätsprüfungen der API wurde beschlossen, den Bezeichner `schemas`, der die referenzierten Fachdatenschemata in der Destination bzw. im Metadatenschema beinhaltet, in `submissionSchemas` umzubenennen. Diese Umbenennung wurde in der API Spec und Dokumentation ungepasst.
Im Rahmen der Qualitätsprüfungen der API wurde beschlossen, den Bezeichner `schemas`, der die referenzierten Fachdatenschemata in der 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
#### Dokumentationsartikel "Versenden" im Überblick von Getting Started aufteilen
...
Um einen besseren Einstieg für Entwickler von sendenden Systemen zu ermöglichen, wurden Inhalte aus dem Artikel "Überblick" in einen Artikel "Zustellpunkt ermitteln" überführt, der detaillierter beschreibet, wie im aktuell die korrekte destinationId des gewünschten Zustellpunkts ermittelt werden kann und wie die Informationen eines Zustellpunkts für die Datenübermittlung zu nutzen sind.
### Im Sprint nicht abgeschlossene Stories
### Im Sprint nicht abgeschlossene Stories
#### Umsetzung des Self-Service-Portals
#### Umsetzung des Self-Service-Portals
...
Das Self-Service-Portal soll in der ersten MVP Ausbaustufe zwei Funktionen erfüllen:
- Entwickler und Verfahrensbetreiber sollen ihre Software als API-Clients registrieren können und deren Berechtigungen (Scopes) verwalten können.
- Entwickler und Verfahrensbetreiber von empfangenden Systemen können über das Self-Service-Portal Zustellpunkte einrichten und verwalten.
#### XFall Schema: Erstellung eines Konzepts zur Ableitung eines JSON Schemas aus einem FIM Stammdatenschema
Das Self-Service-Portal wird bis kommende Woche für die Nutzung für die öffentliche Test-API bereitgestellt. Interessierten Entwickler 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
## Roadmap Update
...
Um die Nutzung von FIM für 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
Bei Fragen, Hinweisen oder Wünschen freuen wir uns gerne über Feedback. Dieses bitte über
