From 74d89c98a35c07c009c571a7c41c07572ee362c1 Mon Sep 17 00:00:00 2001 From: David Schwarzmann <david.schwarzmann@codecentric.de> Date: Wed, 9 Jun 2021 09:39:49 +0000 Subject: [PATCH] Mark documents --- docs/1_Getting_Started.md | 2 ++ docs/2_Quick_Reference.md | 2 ++ docs/3_Use_Cases_der_API.md | 5 +++++ docs/4_Authentifizierung_und_Autorisierung.md | 2 ++ "docs/6_Architektur_\303\234bersicht.md" | 2 ++ docs/Detailinformationen/Antrag_Event_Log.md | 4 +++- .../Authentifizierung_von_Fachanwendungen.md | 2 ++ docs/Detailinformationen/Authentifizierung_von_Usern.md | 4 +++- docs/Detailinformationen/Begrenzung_von_Abrufen.md | 6 ++++-- docs/Detailinformationen/Encryption.md | 5 ++++- docs/Detailinformationen/Encryption_Key_Requirements.md | 3 +++ docs/Detailinformationen/Glossar.md | 2 ++ docs/Detailinformationen/Metadaten.md | 2 ++ docs/Detailinformationen/OAuth.md | 2 ++ docs/Detailinformationen/Postman.md | 2 ++ docs/Detailinformationen/Zustellberechtigungs-Scopes.md | 2 ++ docs/_Overview.md | 8 ++++++++ 17 files changed, 50 insertions(+), 5 deletions(-) diff --git a/docs/1_Getting_Started.md b/docs/1_Getting_Started.md index 921aca13..f761da02 100644 --- a/docs/1_Getting_Started.md +++ b/docs/1_Getting_Started.md @@ -1,5 +1,7 @@ # Erste Schritte zur API Nutzung +- Veraltet, muss aktualisiert werden bzw. in mehrere Tutorial-Steps aufgeteilt werden + ## ①Account registrieren > Registrieren Sie sich für ein Zugriff, um mit Ihren Client auf die API zuzugreifen. Im Rahmen der Registrierung bekommen Sie für die gewünschte API die Client-ID und Zugriffdaten mitgeteilt. Da zum aktuellen Zeitpunkt keine Sandbox Umgebung bereitstellt, wird empfohlen, sich für beide Seiten zu registieren, um für komplexere Tests mit einem REST Client die API der Gegenseite anzusprechen (Siehe Postman Nutzung in Schritt 2). ➡ [Registrierung zur API Nutzung](./4_Authentifizierung_und_Autorisierung.md) diff --git a/docs/2_Quick_Reference.md b/docs/2_Quick_Reference.md index fb4b6326..2daeb29c 100644 --- a/docs/2_Quick_Reference.md +++ b/docs/2_Quick_Reference.md @@ -1,5 +1,7 @@ # API-Kurzreferenz +- Löschen + ## Der XFall Antrag  diff --git a/docs/3_Use_Cases_der_API.md b/docs/3_Use_Cases_der_API.md index cf695e45..46d3fb8d 100644 --- a/docs/3_Use_Cases_der_API.md +++ b/docs/3_Use_Cases_der_API.md @@ -1,5 +1,10 @@ # Anwendungsfälle der API +- Sources f. Grafiken nicht vorhanden => Müssen überarbeitet werden +- Assets löschen (fiep-poc auf GH) +- UC checken, ob alle vorhanden sind +- Bringt einem API Nutzer wenig, bis gar nix => Für Betreiber relevant oder in Konzeption verschieben? Betreiberdoku in Konzeptions-Repo?) + ## Gesamtüberblick der Anwendungsfälle und beteiligten Fachsysteme  diff --git a/docs/4_Authentifizierung_und_Autorisierung.md b/docs/4_Authentifizierung_und_Autorisierung.md index 71b1fdfa..fe262d4c 100644 --- a/docs/4_Authentifizierung_und_Autorisierung.md +++ b/docs/4_Authentifizierung_und_Autorisierung.md @@ -1,5 +1,7 @@ # Registrierung und Client-Verwaltung +**=> Kann weg** + Der bisherige Proof of Concept ist ausgelaufen und FIT-Connect wird nun als Projekt des IT-Planungsrats aufgebaut. Im Rahmen der Projektumsetzung wird die aktuelle API finalisiert und technisch umgesetzt. Bei Interesse an einem Zugang zu einem Testsystem zur technischen Evaluierung der Anbindung von Fachverfahren und Onlinediensten an FIT-Connect melden Sie sich gerne unter fit-connect@fitko.de. diff --git "a/docs/6_Architektur_\303\234bersicht.md" "b/docs/6_Architektur_\303\234bersicht.md" index 6902d731..736e4531 100644 --- "a/docs/6_Architektur_\303\234bersicht.md" +++ "b/docs/6_Architektur_\303\234bersicht.md" @@ -1,5 +1,7 @@ # FIT-Connect Architektur Übersicht +=> Zusammenführen mit anderen Dokumenten (Overview) + FIT-Connect ist ein System, das es ermöglicht, Anträge von einem Onlineservice, einer App oder einem anderen digitalen Medium über eine standartisierte Schnittstelle an die zuständige Person bzw. an ein Fachverfahren in der für den Antrag zuständigen Behörde zu versenden. Dafür gibt es zwei Schnittstellen zum FIT-Connect-System die Abgabepunkt-API und die Zustellpunkt-API. diff --git a/docs/Detailinformationen/Antrag_Event_Log.md b/docs/Detailinformationen/Antrag_Event_Log.md index 975540a7..afab3117 100644 --- a/docs/Detailinformationen/Antrag_Event_Log.md +++ b/docs/Detailinformationen/Antrag_Event_Log.md @@ -1,5 +1,7 @@ # Eventlog eines Antrags +- Wird durch Security Event Log ersetzt, ist konzeptionell, aber auch für Nutzer relevant + Jeder eingegangene Antrag verfügt über einen Eventlog, indem Statusänderungen am Antrag festgehalten werden. Das ist zu vergleichen mit einem Sendungsverfolgungssystem bei einem Paketdienst und dient einerseits dazu, die Nutzer*innen über den Status ihres Antrags zu informieren und andrerseits stellte ist es eine signierte Nachweiskette, die beweisen kann, das ein Antrag übermittelt und bei der Fachanwendung eingegangen ist. Der Eventlog basiert auf dem Prinzip der Security Event Tokens [RFC 8417](https://tools.ietf.org/html/rfc8417). Einträge können einerseits durch de Übermittlungsdienst und andrerseits die Fachanwendung hinzugefügt werden. @@ -32,4 +34,4 @@ Zur Übermittlug der Tokens wird das in [RFC 7515, Abschnitt 7.1](https://tools. ## Darstellen des Eventlogs -Wenn ein Onlinedienst den Eventlog darstellen möchte, muss dieser sicherstellen, das die im Eventlog enthaltenen Einträge über eine valide Signatur verfügen und falls sich Einträge mit einer invaliden Signatur im Eventlog befinden, muss das für den User erkennbar sein. \ No newline at end of file +Wenn ein Onlinedienst den Eventlog darstellen möchte, muss dieser sicherstellen, das die im Eventlog enthaltenen Einträge über eine valide Signatur verfügen und falls sich Einträge mit einer invaliden Signatur im Eventlog befinden, muss das für den User erkennbar sein. diff --git a/docs/Detailinformationen/Authentifizierung_von_Fachanwendungen.md b/docs/Detailinformationen/Authentifizierung_von_Fachanwendungen.md index aa84b87b..df605e5a 100644 --- a/docs/Detailinformationen/Authentifizierung_von_Fachanwendungen.md +++ b/docs/Detailinformationen/Authentifizierung_von_Fachanwendungen.md @@ -1,5 +1,7 @@ # Authentifizierung von Fachanwendungen +**=> Beschreibt Zielkonzept, aber nich von v1, dadurch in Konzeption-Repo verschieben** + Fachanwendungen haben die Möglichkeit FIT-Connect Anträge abzurufen. Dafür müssen sie sich mithilfe von oauth2 "Client-Credentials" authentifizieren. Diese erhalten Behörden und andere Abrufberechtigte, nach einer Anmeldung im Self-Service-Portal der FITKO. (TODO: link) Für jede Destination müssen folgende Informationen im Self-Service-Portal bereitgestellt werden diff --git a/docs/Detailinformationen/Authentifizierung_von_Usern.md b/docs/Detailinformationen/Authentifizierung_von_Usern.md index 7915c935..25fe95b9 100644 --- a/docs/Detailinformationen/Authentifizierung_von_Usern.md +++ b/docs/Detailinformationen/Authentifizierung_von_Usern.md @@ -1,5 +1,7 @@ # Authentifizierung von Usern an Zustelldiensten +**=> Beschreibt Zielkonzept, aber nich von v1, dadurch in Konzeption-Repo verschieben** + Jeder Onlineantragsdienst muss bei FIT-Connect registriert sein, um FIT-Connect Formulare darstellen und übermitteln zu können. Bei der Registrierung von Onlinediensten wird festgelegt, welche Anträge die Onlinedienste auf welchen Domains ausspielen dürfen. Im Rahmen dieses Prozesses wird für jeden Onlinedienst außerdem ein Public Key hinterlegt. Nach der Anmeldung erhält jeder Onlineantragsdienst OAuth2-Credentials für den Authentifizierungstyp "Client-Credentials". Eine Registrierung eines Onlinedienstes ist über das Self-Service-Portal der FITKO möglich. (TODO: link) Dort müssen folgende Informationen über einen Onlinedienst hinterlegt werden: @@ -143,4 +145,4 @@ Das API-Gateway muss die JWT-Tokens validieren: - sid - IP-Addresse des Users - Website von der der Antrag übermittelt wird bzw. das Fehlen eines Referers -- Onlineservice-ID \ No newline at end of file +- Onlineservice-ID diff --git a/docs/Detailinformationen/Begrenzung_von_Abrufen.md b/docs/Detailinformationen/Begrenzung_von_Abrufen.md index f6a21d5a..60e71504 100644 --- a/docs/Detailinformationen/Begrenzung_von_Abrufen.md +++ b/docs/Detailinformationen/Begrenzung_von_Abrufen.md @@ -1,7 +1,9 @@ -# Begrenzung von Abrufen +# Begrenzung von Abrufen (Rate-Limiting & Throttling) + +=> Noch nicht definiert ... **Noch in Arbeit** -... \ No newline at end of file +... diff --git a/docs/Detailinformationen/Encryption.md b/docs/Detailinformationen/Encryption.md index 3836e9a9..2e83c114 100644 --- a/docs/Detailinformationen/Encryption.md +++ b/docs/Detailinformationen/Encryption.md @@ -1,5 +1,8 @@ # Verschlüsselte Übertragung +- **Reevaluierung:** Wir machen keine echte E2E-verschlüsselung, daher teilweise inkorrekt (Nutzer hat keinen Private-Key, der Onlinedienst führt die Verschlüsselung durch) +- **=> Beschreibt Zielkonzept, aber nur teilweise v1, dadurch in Konzeption-Repo verschieben und relevante Informationen zusammenfassen** + ## Einleitung FIT-Connect verwendet zur Übertragung von Antragsdaten und Antragsmetadaten (abgesehen von den für die Übermittlung zwingend notwendigen Daten, z.B. Destination-ID) eine Ende-zu-Ende-Verschlüsselung. Diese ist auf Basis der Standards [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) und [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) umgesetzt. @@ -204,4 +207,4 @@ pfGU_7HxX4d-PLEoDfIRnh32nprarbaIesj9Ppgiu7QciWRApcyszk0a5rzZ7Dk_6-ydMfD92H2p3tdt OcFhj3XGUshVKec2nRhtCZPOMPTIjxFpozsiRetjZo9LFHzRcvr1eSS_hpteKJ3ltioY9nzt1IX2JqQm TGtY.VGOCnGM9LEZP5mUO.LQeKj4SKqsUNsBp4ZRN_56QbS8MQ01YTzRVFStk.Z0YMEua9kvCV7LkeJH kprA -``` \ No newline at end of file +``` diff --git a/docs/Detailinformationen/Encryption_Key_Requirements.md b/docs/Detailinformationen/Encryption_Key_Requirements.md index 1fa50a28..cbb35b4d 100644 --- a/docs/Detailinformationen/Encryption_Key_Requirements.md +++ b/docs/Detailinformationen/Encryption_Key_Requirements.md @@ -1,5 +1,8 @@ # Vorgaben für kryptographische Verfahren beim Einsatz von FIT-Connect +- **=> Beschreibt Zielkonzept, dadurch in Konzeption-Repo verschieben und relevante Informationen zusammenfassen** +- Eher interessant: Wie bekomme ich Zertifikate für einen Testserver. Im Produktivbetrieb kommen die Informationen aus der Verwaltungs-PKI (noch unklar) + FIT-Connect verwendet zur Übertragung von Antragsdaten und Metadaten mit direktem Bezug zu Anträgen eine Ende-zu-Ende-Verschlüsselung. Diese ist auf Basis des Standards [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) unter Verwendung von Schlüsseln gemäß des Standards [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) umgesetzt. Zudem bietet FIT-Connect digital signierte Eingangsbestätigungen für Anträge. Die ausgestellten Signaturen werden auf Basis von [Security Event Tokens (SET)](https://tools.ietf.org/html/rfc8417) erzeugt und die dazugehörigen Schlüssel gemäß des Standards [JSON Web Keys (JWK)](https://tools.ietf.org/html/rfc7517) implementiert. diff --git a/docs/Detailinformationen/Glossar.md b/docs/Detailinformationen/Glossar.md index 81f04b2d..307b8324 100644 --- a/docs/Detailinformationen/Glossar.md +++ b/docs/Detailinformationen/Glossar.md @@ -1,5 +1,7 @@ # Glossar +- Veraltet, mit Confluence mergen? + <dl> <dt>Application</dt> diff --git a/docs/Detailinformationen/Metadaten.md b/docs/Detailinformationen/Metadaten.md index 51dc7b9a..2d060070 100644 --- a/docs/Detailinformationen/Metadaten.md +++ b/docs/Detailinformationen/Metadaten.md @@ -1,5 +1,7 @@ # Antragsmetadaten +=> Wird zerlegt in mehrere Schritte in neuer Docu + Die Antragsmetadaten beschreiben die Struktur des Antrags und dessen Inhalte, wie beispielsweise Anhänge oder die Fachdaten. Zustätzlich können weitere Informationen über den/die AntragsstellerInnen hinterlegt werden. Eine genaue Definition ist unter XYZ zu finden bzw. direkt im [Schema](/API_VERSION/antragsmetadaten.schema.json) zu finden. Im Folgenden wird nun beschrieben, wie für das Versenden eines Antrags das Schema aufgebaut und befüllt wird, sowie beim Empfangen eines Antrags dieser entschlüsselt und gegen das Schema validiert wird. diff --git a/docs/Detailinformationen/OAuth.md b/docs/Detailinformationen/OAuth.md index e2cdb74c..3fbc7b00 100644 --- a/docs/Detailinformationen/OAuth.md +++ b/docs/Detailinformationen/OAuth.md @@ -1,5 +1,7 @@ # OAuth Details +- Abgleichen mit Dokumentation von Lilith, ob Code-Beispiele vorhanden, ansonsten kann das weg + ## API Aufruf mit wget Sie können auch mit dem Kommandozeilentool "wget" testen. In diesem Beispiel wird die Liste aller Destinations abgerufen: diff --git a/docs/Detailinformationen/Postman.md b/docs/Detailinformationen/Postman.md index 3a32dfeb..04efa20d 100644 --- a/docs/Detailinformationen/Postman.md +++ b/docs/Detailinformationen/Postman.md @@ -1,5 +1,7 @@ # Testen mit Postman +=> Kann weg + Für Tests kann auch SoapUI oder jeder andere REST Client mit OAuth 2.0 Unterstützung eingesetzt werden. Unter diesen beiden Adressen können Sie eine Postman Collection und eine Postman Environment herunterladen: - [Collection](https://raw.githubusercontent.com/fiep-poc/assets/master/postman/FIT-Connect.postman_collection.json) diff --git a/docs/Detailinformationen/Zustellberechtigungs-Scopes.md b/docs/Detailinformationen/Zustellberechtigungs-Scopes.md index 68cf573f..8cd852a3 100644 --- a/docs/Detailinformationen/Zustellberechtigungs-Scopes.md +++ b/docs/Detailinformationen/Zustellberechtigungs-Scopes.md @@ -1,5 +1,7 @@ # Zustellberechtigungs-Scope + **=> Beschreibt Zielkonzept, dadurch in Konzeption-Repo verschieben** + Die Zustellberechtigungs-Scopes erlauben dem Zustelldienst festzustellen, ob ein dort eingesendeter Antrag vom Versender an eine Destination übermittelt werden darf. ## Zusammensetzung der Zustellberechtigungs-Scopes diff --git a/docs/_Overview.md b/docs/_Overview.md index baeca6a5..69d57ccf 100644 --- a/docs/_Overview.md +++ b/docs/_Overview.md @@ -1,5 +1,13 @@ # Überblick über die XFall API +// Autor: Alexander, nachfragen + + +- Wie bekomme ich mein Token, wie lang ist es gültig, Prozessüberblick, über Authentifizierung + +- APIs (Application, Subscriber, Sender, XFall) vereinheitlichen & umbenenen +- **XFall reevaluieren**, welche Bedeutung bzw. Relevanz in Dokumentation => Politische Entscheidung von Marco/Alexander notwendig (IT-Planungsrat) + Willkommen auf der API Dokumentation für die XFall REST API von FIT-Connect. Die XFall API baut auf dem bestehenden IT-Planungsrat Standard XFall auf und bietet Lösungsverantwortlichen von antragssendenden und antragsempfangenden Systemen eine einfache Möglichkeit, ihre Software schnell und wirtschaftlich in länder- und ebenenübergreifende Antragsprozesse zu integrieren. ## Was ist die XFall API und was unterscheidet diese API vom bisherigen XFall Standard? -- GitLab