Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • fit-connect/submission-api
  • Lilith_Wittmann/FIT-Connect-PoC
2 results
Show changes
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 3920 additions and 2552 deletions
assets/images/use_case_documentation/application_retrieval.png deleted 100644 → 0
View file @ 1b6edfde
assets/images/use_case_documentation/application_retrieval.png

124 KiB

assets/images/use_case_documentation/application_transfer.png deleted 100644 → 0
View file @ 1b6edfde
assets/images/use_case_documentation/application_transfer.png

91.5 KiB

assets/images/use_case_documentation/use_case_diagramm.png deleted 100644 → 0
View file @ 1b6edfde
assets/images/use_case_documentation/use_case_diagramm.png

64.3 KiB

assets/postman/FIT-Connect.postman_collection.json deleted 100644 → 0
View file @ 1b6edfde
This diff is collapsed.
assets/postman/FIT-Connect.postman_environment.json deleted 100644 → 0
View file @ 1b6edfde
{
"id": "44204631-99ff-4de7-92e1-76fc41b2b798",
"name": "FIT-Connect",
"values": [
{
"key": "sender_url",
"value": "https://sender.fiep-poc.de/beta6/",
"enabled": true
},
{
"key": "subscriber_url",
"value": "https://subscriber.fiep-poc.de/beta6/",
"enabled": true
},
{
"key": "sender_id",
"value": "sender-c94ae37e-dcc5-345e-a530-8651bdfa5f2c",
"enabled": true
},
{
"key": "subscriber_id",
"value": "subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c",
"enabled": true
},
{
"key": "sender_url2",
"value": "https://sender.fiep-poc.de/beta6/",
"enabled": true
}
],
"_postman_variable_scope": "environment",
"_postman_exported_at": "2020-05-19T06:38:54.721Z",
"_postman_exported_using": "Postman/7.24.0"
}
\ No newline at end of file
ci/index.html 0 → 100644
View file @ 28a5895d
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<script type="module" src="rapidoc.js"></script>
</head>
<body>
<rapi-doc
spec-url="./submission-api.yaml"
render-style="view"
layout="column"
theme="light"
show-info="false"
show-header="false"
show-components="false"
allow-spec-file-load="false"
info-description-headings-in-navbar="false"
allow-try="false"
primary-color="#11171a"
allow-server-selection="false"
server-url=""
schema-description-expanded="true"
></rapi-doc>
</body>
</html>
ci/rapidoc.js 0 → 100644
View file @ 28a5895d
This diff is collapsed.
docs/1_Getting_Started.md deleted 100644 → 0
View file @ 1b6edfde
# Erste Schritte zur API Nutzung
<!-- theme: info -->
> ## ① 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)
> ## ② API ausprobieren
> In der Navigation auf linken Seite finden Sie die jeweiligen API Referenzen für die Nutzung der APIs unter den Reitern `Application Sender API` und `Application Subscriber API`
Für einen einfachen Einstieg zum Test der API können Sie die bereitgestellte Postman Collection nutzen und mit dem Postman REST Client die Anfragen an die API durchführen. Hiermit können Sie auch die Gegenseite (Sender oder Empfänger von Anträgen simulieren) (➡ [Testen mit Postman](./Detailinformationen/Postman.md). Nähere Informationen zu Postman siehe https://www.postman.com/)
Alternativ können Sie die Anfragen auch mittels eigener Anwendungen oder alternativer REST Clients durchführen.
> ## ③ OAuth Token vor der API Nutzung abrufen
> Für jede Anfrage an die API Endpunkte ist ein gültiger JWT-Token mit der Anfrage mitzusenden. Für nähere Informationen zum Abruf eines JWT-Token siehe ➡ [OAuth Details](./Detailinformationen/OAuth.md)
> ## ④ Spezifikation lokal nutzen
> Sofern Sie einen lokalen Zugriff auf die Quellen der Spezifikation im OpenAPI Format (bspw. für Code Generatoren) benötigen, finden Sie diese hier: ➡[FIT-Connect-PoC-v0.6.zip](https://github.com/fiep-poc/assets/raw/master/spec/FIT-Connect-PoC-v0.6.zip)
## Beispiel mit `curl`
Token holen und in `$TOKEN` speichern:
```bash
TOKEN=$(curl --silent --location --request POST https://sender-test-token.fiep-poc.de/auth/realms/test/protocol/openid-connect/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=beispiel' \
--data-urlencode 'client_secret=29e03d25-7999-4e4c-aa9a-bb2b99404d09' \
--data-urlencode 'scope=destination:send' \
--data-urlencode 'grant_type=client_credentials' \
| jq -r .access_token)
```
Sie können das Token mit `echo ${TOKEN}` ausgeben lassen.
Server Version abfragen (API Test):
```bash
curl --silent --header "Authorization: Bearer ${TOKEN}" https://sender-test.fiep-poc.de/beta7/info
```
## Wie geht es weiter?
<!-- theme: success -->
> ### Service Desk
> Für Fragen, Anregungen und sonstiges Feedback steht Ihnen unser
> [FIT-Connect Service Desk](https://jira.fiep-poc.de/servicedesk/customer/portal/1)
> zur Verfügung.
docs/2_Quick_Reference.md deleted 100644 → 0
View file @ 1b6edfde
# API-Kurzreferenz
## Der XFall Antrag
![application_structure](https://raw.githubusercontent.com/fiep-poc/assets/master/images/quick_reference/application_structure.png "Struktur des XFall Antrags")
Der XFall Antrag (`application`) ist das zentrale Geschäftsobjekt in der XFall API. Der XFall Antrag besteht aus den Fachdaten (`data`) sowie den beigefügten Anhängen (`document`) und wird über die Metadaten ([application metadata](../models/application/metadata.json)) beschrieben.
Die Metadaten des Antrags entsprechen dem früheren XFall-Container und enthalten übergreifenden Informationen über den Antrag sowie Strukturinformationen zu den enthaltenen Fachdaten und Anhängen.
Fachdaten bezeichnen in XFall Antrag im einen strukturieren Datensatz in XML oder JSON und können über ein externes Schema (bspw. aus FIM) beschrieben werden.
Anhänge können entweder klassische Anhänge (bspw. Nachweise) oder oder eine PDF-Repräsentation der Fachdaten des Antrags, falls eine solche alternative Repräsentation aus rechtlichen, technischen oder organisatorischen Gründen notwendig ist.
## Identifikatoren der XFall Ressourcen
Um Ressourcen eindeutig zu identifizieren, werden in den URLs der REST Endpunkte eine oder mehrere Identifikatoren (IDs) benutzt.
### Von der API bereitgestellte IDs
#### applicationId
Der Zustelldienst weist jedem übertragenen Antrag (`application`) eine global eindeutige `applicationId` zu, die diesen Antrag dauerhaft über den gesamten Bearbeitungsverlauf eindeutig identifiziert.
#### destinationId
Die `destinationId` ist eine vom Zustelldienst vergebene ID für einen durch den Subscriber angelegten Zustellpunkt (`destination`). Diese ID wird dem Sender über externe Systeme (bspw. Zuständigkeitsfinder) oder bilaterale Absprachen zwischen beiden Seiten mitgeteilt.
### Vom Sender vergebene Identifikatoren
#### docId
Der Sender vergibt für jedes Antragsformular und jede Anlage in einer Übertragung eine `docId`. Diese muss für alle Dokumente (PDF-Antragsformulare und beliebige Anlagen) in der Übertragung eindeutig sein. Es wird empfohlen, die IDs `1`, `2` etc. zu verwenden.
## Operation der Application Sender API
Mit folgenden Operationen kann der Sender eine Application übertragen und die Übertragung verwalten:
- [Create Application](../reference/sender.json/paths/~1destinations~1{destinationId}~1applications/post) - Legt eine neue Übertragung durch Übermittlung der Metadaten an.
- [Add Application Data](../reference/sender.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}~1data/put) - Fügt dem Antrag strukturierte Daten (Fachdaten) hinzu.
- [Add Application Document](../reference/sender.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}~1docs~1{docId}/put) - Übermittelt ein Antragsformular oder eine Anlage.
- [Send Application](../reference/sender.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}/post) - Beendet die Übertragung des Antrags und löst seinen Versand aus.
- [Get Application Upload Status](../reference/sender.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}~1upload-status/get) - Ruft den Status der Uploads der Teile der Übertragung ab. Für die Fachdaten und Dokumente wird jeweils der Status und die auf dem Server vorliegende Länge in Bytes zurückgegegben.
Darüber hinaus stehen dem Sender folgende weitere Operationen zur Verfügung:
- [Get Destination Info](../reference/sender.json/paths/~1destinations~1{destinationId}/get) - Ruft übertragungsrelevante Informationen über den Zustellpunkt (bspw. zulässige Schemata oder Datentypen) ab.
- [Get Status](../reference/sender.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}~1status/get) - Ruft den Status sowie die Statushistorie der Zustellung des Antrags ab.
## Operation der Application Subscriber API
Mit diesen Operationen kann der Subscriber eine oder mehrere Zustellpunkte (`Destinations`) verwalten:
- [Create Destination](../reference/subscriber.json/paths/~1destinations/post) - Legt ein neues Übertragungsziel (Destination) an.
- [List Destinations](../reference/subscriber.json/paths/~1destinations/get) - Listet alle Übertragungsziele (Destinations) eines Subscribers auf.
- [Get Destination](../reference/subscriber.json/paths/~1destinations~1{destinationId}/get) - Ruf die Daten eines Übertragungsziels (Destination) ab.
- [Update Destination](../reference/subscriber.json/paths/~1destinations~1{destinationId}/put) - Aktualisiert ein Übertragungsziel (Destination).
- [Delete Destination](../reference/subscriber.json/paths/~1destinations~1{destinationId}/delete) - Löscht ein Übertragungsziel (Destination).
Mit diesen Operationen wird nach wartenden Applications gesucht und diese abgeholt:
- [List Applications](../reference/subscriber.json/paths/~1destinations~1{destinationId}~1applications/get) - Ruft die Liste der wartenden Übertragungen (Applications) ab.
- [Get Application Metadata](../reference/subscriber.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}/get) - Ruft eine wartende Übertragung (Application) ab.
- [Get Application Data](../reference/subscriber.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}~1data/get) - Ruft die Fachdaten einer Übertragung (Application Data) ab.
- [Get Application Document](../reference/subscriber.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}~1docs~1{docId}/get) - Ruf ein Dokument (Formular oder Anlage) der Application ab.
- [Acknowledge Application](../reference/subscriber.json/paths/~1destinations~1{destinationId}~1applications~1{applicationId}/post) - Quittiert die Abholung der Übertragung.
docs/3_Use_Cases_der_API.md deleted 100644 → 0
View file @ 1b6edfde
# Anwendungsfälle der API
## Gesamtüberblick der Anwendungsfälle und beteiligten Fachsysteme
![Application_Transfer](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/use_case_diagramm.png "Use Case Diagramm der XFall APIs")
## Anwendungsfälle für antragssendende Systeme (Sender)
### Antrag bei einem Zustellpunkt abgeben
**Vorbedingung:** Es muss zuvor die `destination-id` eines gültigen Zustellpunkts ermittelt worden sein. Im Rahmen des PoC erfolgt die Übermittlung mittels bilateraler Absprachen und Kanäle zwischen dem Subscriber und Sender. Zukünftig soll diese Ermittlung über die API eines Zuständigskeitsfinders für die gewünschte Verwaltungsleistung und den Ortsbezug erfolgen, wenn die `destination-id` in den dortigen Zuständigkeitsinformation durch die zuständige Stelle hinterlegt wurde.
**Ziel:** Alle Bestandteile des Antrags werden in den Abholbereich des addressierten Zustellpunkts übergeben und liegen dort zur Abholung durch den Subscriber bereit.
**Beschreibung:** Falls die Parameter des Zustellpunkts (bspw. das zu nutzendes Fachdatenschema des Antrags) nicht bekannt sind, können diese Information über die Angabe der Destination-ID abgerufen werden. Zur Initierung der Übertragung, überträgt der Sender mittels eines POST die Metadaten des Antrags an die Sender API und legt damit den Antrag (`application`) als Ressource und die Fachdaten sowie die in den Metadaten angegebenen Anlagen als Subressourcen an. Für den Antrag bekommt der Sender eine eindeutige `application-id`in der Response mitgeteilt. Der Sender kann anschließend alle Bestandteile des Antrags an die jeweiligen Endpunkte per PUT übermitteln und die Übergabe an in den Abholbereich des Subscribers über einen abschließenden Commit initialisieren.
![Application_Transfer](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/application_transfer_API_V6.png "Ablaufbeschreibung zur Uebertragung eines Antrags")
### Zustellstatus des abgegebenen Antrags abrufen
**Vorbedingung:** Der Antrag wurde als Ressource angelegt und dem Sender liegt eine `application-id` vor.
**Ziel:** Den Zustellungsstatus des Antrags abschließend überwachen.
**Beschreibung:** Der Sender fragt per GET über die `application-id` den `status` der Antrags ab. Als Antwort bekommt dieser den aktuellen Status sowie die Statushistorie übersendet. Diese Statusübergänge sind über standardisierte Codes (`incomplete`, `queued`, `forwarded`, `delivered`) definiert.
## Anwendungsfälle für antragsempfangende Systeme (Subscriber)
### Zustellpunkt einrichten
**Vorbedingung:** Keine
**Ziel:** Es wird ein Zustellpunkt (`destination`) eingerichtet und verwaltet, über den der Subscriber Anträge empfangen kann. Hierdurch wird grundsätzlich ein Zugang für alle Sender eröffnet, die die `destination-id` kennen.
**Beschreibung:** Der Subscriber erstellt einen Zustellpunkt per POST und bekommt von der API eine eindeutige `destination-id`. Für diesen Zustellpunkt sind fachliche und technische Ansprechpartner sowie das Schema der Fachdaten zu definieren. Zusätzlich besteht die Möglichkeit, eine Callback URL zu hinterlegen, über die der Zustelldienst den Subscriber über neue Anträge informieren kann.
### Benachrichtigungen über Anträge erhalten
**Vorbedingung:** Es wurden in den Zustellpunkten Callback URLs hinterlegt, die durch den XFall Zustelldienst erreichbar sind.
**Ziel:** Ziel ist, Benachrichtigungen über abholbereite Anträge zu empfangen. Diese Benachrichtigungen ersetzen ein konstantes Polling durch den Subscriber und entlasten damit die verfügbaren Hardware und Netzwerkressourcen.
**Beschreibung:** Für die Benachrichtung übernimmt der Subscriber die Rolle eines API Providers, indem dieser Requests vom Zustelldienst empfängt. Der Zustelldienst sendet beim Vorliegen einer oder mehrerer Anträge einen POST Request mit allen `application-id's` der abholbereiten Anträge an die hinterlegte Callback URL.
### Anträge abrufen
**Vorbedingung:** Der Subscriber hat einen Zustellpunkt erstellt und die dazugehörige `destination-id` einem oder mehreren Sendern mitgeteilt und es liegt einer oder mehrere Anträge zum abholen bereit.
**Ziel:** Ziel ist es, abholbereite Anträge abzurufen.
**Beschreibung:** Der Subscriber kann die Metadaten aller vorliegenden Anträge mit einem Request abrufen oder die Metadaten eines spezifischen Antrags abrufen, falls die `application-id` durch eine Callback Benachtigung bereits mitgeteilt wurde. Nach dem Abruf der Metadaten besteht die Möglichkeit, die Fachdaten (`data`) sowie die Anlagen (`document`) abzurufen. Nach dem Abruf aller gewünschten Bestandteile des Antrags, muss der vollständige Abruf durch den Subscriber bestätigt werden. Diese Bestätigung hat zur Folge, dass innerhalb einer definierten Frist der Antrag unwiederruflich gelöscht wird.
![Application_Retrieval](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/application_retrieval_API_V6.png "Ablaufbeschreibung zum Abruf eines Antrags")
### Legende der verwendeten BPMN Symbole
#### Start- und Endereignisse
![Start_Event](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/BPMN%20Legend/Start_Event.png "Startereignis")
![End_Event](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/BPMN%20Legend/End_Event.png "Endereignis")
Startet oder beendet einen Prozessablauf.
#### Aktivität
![Activity](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/BPMN%20Legend/Activity.png "Aktivität")
Eine Tätigkeit innerhalb einer Prozessablaufs.
#### Aktivität mit mehrfachen parallelen Instanzen
![Activity_Multi_Instance](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/BPMN%20Legend/Activity_Multi_Instance.png "Aktivität mit mehrfachen parallelen Instanzen")
Eine Tätigkeit innerhalb einer Prozessablaufs, die ab dem aktivierungszeitpunkt mehrfach parallel durchgeführt werden kann.
#### Exclusive Gateway
![Exclusive Gateway](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/BPMN%20Legend/Exclusive%20Gateway.png "Exklusives Gateway")
Ein Entscheidungspunkt innerhalb des Prozessablaufs im Sinne einer ODER Entscheidung. Es wird nur der weitere Prozessablauf weiterverfolgt, der dem Entscheidungsergebnis entspricht.
#### Parallel Gateway
![Parallel Gateway](https://raw.githubusercontent.com/fiep-poc/assets/master/images/use_case_documentation/BPMN%20Legend/Parallel_Gateway.png "Paralleles Gateway")
Parallelisierungspunkt innerhalb des Prozessablauf. Prozessflüsse nach dem parallelen Gateway parallel durchgeführt.
docs/4_Authentifizierung_und_Autorisierung.md deleted 100644 → 0
View file @ 1b6edfde
# Registrierung und Client-Verwaltung
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.
Daher wird von der FITKO kein offizieller Testbetrieb mehr angeboten. Sollte ein Interesse an einer technischen Evalierung bestehen, dann melden Sie sich bei fit-connect@fitko.de.
## Hinweise zum Aufruf der API mit OAuth2
Um das von ihnen gewünschte API im Rahmen ihrer Anwendung aufzurufen, Gehen sie wie folgt vor:
![API Zugriff](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/13_api_zugriff.png)
Verfahrensschritte:
1) Die Clientanwendung sendet die Authentifizierungsanforderung an den Autorisierungsserver, um ein Zugriffstoken zu erhalten.
2) Der Autorisierungsserver überprüft die Anforderung und generiert ein Zugriffstoken für den Client.
3) Der Client verwendet dieses Zugriffstoken, um HTTP-Anforderungen an das API-Gateway zu senden.
4) Das API-Gateway führt dann folgendes aus:
- Identifiziert die Anwendung anhand der client_Id.
- Überprüft das Token lokal oder remote, wenn es lokal nicht möglich ist.
- Überprüft, ob die angeforderte Ressource Teil des Bereichs im Token ist.
Wurden alle Prüfschritte erfolgreich absolviert, wird die Anfrage an den Zustelldienst übergeben.
Nach Bearbeitung der Anfrage im Zustelldienst wird die Antwort des Zustelldienstes an den Client zurückgesendet.
FÜr nähere Details und Beispiele siehe:
➡ [OAuth](./Detailinformationen/OAuth.md)
docs/5_Status-_und_Fehlercodes.md deleted 100644 → 0
View file @ 1b6edfde
This diff is collapsed.
docs/Detailinformationen/Begrenzung_von_Abrufen.md deleted 100644 → 0
View file @ 1b6edfde
# Begrenzung von Abrufen
...
**Noch in Arbeit**
...
\ No newline at end of file
docs/Detailinformationen/Callback.md deleted 100644 → 0
View file @ 1b6edfde
# Callback Benachrichtigungen
Callbacks sind einfache Webhooks und dienen dazu, API Nutzer über relevante Ereignisse aktiv zu informieren, anstatt das der Client über konstante Abfragen an der API potentielle Änderungen oder Eigenisse abzufragen muss.
Aktuell wird den Subscribern eine Callback Funktion angeboten, um diese über abrufbereite Anträge in ihren Destinations zu informieren.
## Callback registrieren
Beim [anlegen](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations/post) oder [aktualisieren](../reference/subscriber.json/paths/~1{subscriber-id}~1destinations~1{destination-id}/put) einer Destination sollte ein Callback angegeben werden.
```json
{
"organization": {
"organization-name": "Gewerbeamt Musterhausen"
},
"technical-contact": [
{
"first-name": "Werner",
"last-name": "Mustermann",
"contact": {
"telephones": [
{
"number": "+49 89 32168-42",
"mobile": false,
"type": "work"
}
]
}
}
],
"callback": {
"callback-url": "https://www.example.com/callback"
}
}
```
## Callback ausführen
Trifft nun ein neuer Antrag ein, so sendet der Zustelldienst einen HTTP-POST-Request an die angegebene Adresse. Im Body des Requests werden die `destination-id` und die `application-id`s der wartenden Anträge (i.d.R. genau eine) aufgelistet.
```json
{
"destination-id": "821",
"applications": [
{
"application-id": "98472"
}
]
}
```
## Callback nur bei Inaktivität
Nach einem Callback wartet der Zustelldienst eine gewisse Zeit (z.B. 5 Minuten) bis zum nächsten Callback, auch wenn in dieser Zeit neue Anträge eintreffen. Diese Wartezeit wird bei Aktivität der Destination (z.B. Abfrage der Queue oder Abholen von Anträgen) verlängert.
docs/Detailinformationen/Encryption.md deleted 100644 → 0
View file @ 1b6edfde
# Verschlüsselte Übertragung
## Architektur
![FIT-Connect Architektur](https://raw.githubusercontent.com/fiep-poc/assets/fa582b1bf765cbe5059b5f22f100923da595d6f9/images/encryption/Architektur_PoC_einfach_2.svg "FIT-Connect Architektur")
Kern von FIT-Connect ist der Zustelldienst, der über die beiden APIs "Application Sender API" und "Application Subscriber API" den Absender (Sender) und Empfänger (Subscriber) eines Antrags verbindet.
## Vorgaben
Unter Berücksichtigung der Vorgaben des BSI in der Richtlinie [TR-02102-1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.html) wurden die [Liste der möglichen Algorithmen](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms) eingeschränkt.
- Asymmetrisches Verschlüsselungsverfahren, um den "Content Encryption Key" zu verschlüsseln ("alg"): "RSA-OAEP-256"
- Symmetrisches Verschlüsselungsverfahren zur Verschlüsselung des Payloads ("enc"): "A128GCM" oder "A256GCM"
## Konzept
### Aufbau der Übertragung
Eine Übertragung über FIT-Connect besteht aus einem Metadatensatz, optionalen Fachdaten und beliebig vielen (0-∞) Dokumenten (Anlagen). Da die Metadaten transportrelevante Informationen enthalten, werden diese immer unverschlüsselt übertragen. Bei aktivierter Verschlüsselung werden nur die Fachdaten und Anlagen verschlüsselt.
### Destination
Ein Antrag wird an eine Destination (Zielort) geschickt. Diese Destination legt der Empfänger über die "Application Subscriber API" an. Der Absender muss die ID der Destination kennen und kann dann Anträge über die "Application Sender API" an diese ID senden. Der Empfänger legt in der Destinatin fest, ob die Übertragung optional oder verpflichtend verschlüsselt werden muss. Hierzu enthält die Destination eine Liste von Schemas, aus denen der Absender eines auswählen muss. Diese Schemas enthalten unter anderem eine Angabe zum Encoding, über das eine Verschüsselung vorgegeben wird.
## Application Schema
Das Application Schema wurde in der Beta 7 um die Angabe "encoding" erweitert. Es kann drei verschiedene Werte annehmen: "plain", "base64" und "jwe".
### encoding: plain
"plain" ist der Defaultwert und entspricht der Arbeitsweise bis Beta 6. Hierbei werden die Fachdaten und Anlagen uncodierter Form übermittelt.
#### Beispiel
```json
{"test":true,"hello":"world"}
```
### encoding: base64
"base64" legt fest, dass die Daten base64-codiert übertragen werden.
#### Beispiel
```
eyJ0ZXN0Ijp0cnVlLCJoZWxsbyI6IndvcmxkIn0K
```
### encoding: jwe
Beim Encoding "jwe" werden die Fachdaten und Anlagen mit der JSON Web Encryption (RFC 7516) verschlüsselt.
#### Beispiel
```
eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.nlXGAufYH36IABDy0En0LXEhGfC2
0IZSSchs27ADalHpRoTZKfXhc7hcMk8Y9V8yTP0jYbmrq6NtEg-QS2O5TQFD9Hluhpb631PBgKjPXHYX
1Y6iUcR1sXxSUPjePi8F8PcZUZuUJLnhz6myyc9scdAq9BXG2cDJVgkfLI8eZdrqnrY24Hh32_7d5OKL
FSpSDrBlqfyQuY8Wbs2h8Wy4Z4hwT1aWDO7b-SqJA181hUbNcF_rR4Mze3Fdtu-3uOIQYgLBBRmN1ZHD
Lk0EKNCI4B8MyDKLGPoM0ZomV5lVwVWjAMRI4CgQkIQ9rnm-Adof-GbegQL3yJSoNIWRWgzCnZBYZ638
QgPllCMVW3WvEVvsgj0Hj16PbofqXTQ5S73LINfP6FZawfC0yMrYjSV_N2L0Lkp2KI3BkJcy-PcFhBnh
wu2IsJGAlyDRCnXdVqig8m5yLHuSMQTpLW69LzPEskfsjhnNDR-CEBZpicjMfc-4CL6U7E7YoGc_99Dz
E5U5._JfqyKH23GiKsnDW.ZtMMjZ3GgcgHss8qbFRhrjl4L0kAfbco-oXICkk.VBHJ00FyDTYjOA_OYf
iz5g
```
## Application Subscriber API
Über die Application Subscriber API werden die Destinations verwaltet, an die die Anträge gesenet werden. Eine Destination enthält eine Liste von Schemas, welche Formate der Empfänger akzeptiert. Um sicherzustellen, dass immer eine verschlüsselte Übertragung stattfindet muss jedes dieser Schemas bei der Eigenschaft "encoding" den Wert "jwe" enthalten. Sofern mindestens ein verschlüsseltes Schema angeboten wird, muss auch mindestens ein öffentlicher Schlüssel angeboten werden.
Der Empfänger kann in der Destination mehrere Schemas und mehrere öffentliche Schlüssel hinterlegen. Der Absender sucht sich davon für die Übertragung ein Schema udn einen öffentlichen Schlüssel aus. Es wird empfohlen, genau ein Schema und genau einen öffentlichen Schlüssel anzubieten.
Es ist geplant, dass die hinterlegten öffentlichen Schlüssel so organisiert werden, dass ein kontrolliertes Key-Rollover stattfinden kann. Dazu werden zu den Schlüsseln die Gültigkeitszeiträume ergänzt.
#### Beispiel
```json
{
"publicKeys": {
"keys": [
{
"kty": "RSA",
"e": "AQAB",
"use": "enc",
"kid": "c3bb7326-c498-4027-85f4-b102d0c69ebb",
"n": "zcKRdaV9RjpekpyYqlbXQRhNgs_L2RwerlZKJJWdSaQWCD90yHk-bOlG6gjadalWpL
OF9aOPqqviVKRO2Gq-_mkdBJVuX2pLcx7IuxbEFaFRi81CXPUB3rbKiV_L5bQ2U9_m3X97wV72bkV07R
IJgH9QfCxcGwohN9hU_qLNMfrbwiwOF2WWgxL-x3NpnKhmWiXmIH0b17NH0NTeLTkXnKPWvFmTd_fCwW
Y-Z3L3hQik170z2R-hT4SpQOHN-UhXAbZ-SOER3roGObjHj3K8scFOhyOfd0wUPYP8gX_Lz6nR4AU-Ty
qqfpJ_kaeJdcWbH1z0HWXAenNxTGHOJeyYJGCjctphlSUwJVqrrtNAq15ilFWCw38vvOHbnt8WIqfE-j
hjtz80el2ieb4wQwcwFLGefKcnaNs5K82bIBXF993RqKKKtJfimz8KJAIPYsxpJ9swx4voPjUAdV99Ek
ofh__YzMgEdzoIJ6_pd3nojtm1vRKfcKWiT4Z09DW8qoF1"
}
]
},
"schemas": [
{
"schemaSource": "none",
"mimeType": "json",
"encoding": "jwe"
},
{
"schemaSource": "none",
"mimeType": "xml",
"encoding": "jwe"
}
],
"destinationId": "b444a551-74af-4a98-aa65-d1ffccd385d1"
}
```
## Application Sender API
Der Absender muss die Destination-ID vorliegen haben und erfagt über die Application Sender API die Informationen zur Destination. Diesen entnimmt er die Liste der möglichen Schemas und wählt eines aus. Sofern es sich um eine verschlüsselte Übertragung handelt, wählt er einen öffentlichen Schlüssel.
Derzeit muss die Destination-ID manuell vom Empfänger an den Absender übergeben werden. Dies soll in Zukunft automatisch mithilfe bestehender Mechanismen, z.B. XZufi oder DVDV passieren.
## Übertragungsvarianten
Das gewählte Schema wird in den Metadaten des Antrags (Application Metadata) eingetragen und legt die Art der Übertragung fest. Im folgenden Beispiel wird ein verschlüsselter Fachdatensatz im JSON-Format und ein PDF-Dokument übertragen.
**Hinweis:** Das Encoding der Anlagen ist an das Encoding der Fachdaten gebunden. Alle Anlagen müssen mit dem gleichen Encoding wie die Fachdaten übertragen werden. Hier im Beispiel also verschlüsselt.
#### Beispiel (Metadaten)
```json
{
"contentStructure": {
"data": {
"schema": {
"schemaSource": "none",
"mimeType": "json",
"encoding": "jwe"
}
},
"docs": [
{
"size": 13046,
"purpose": "attachment",
"docId": "1",
"mimeType": "application/pdf"
}
]
},
"applicationId": "6f7b00f1-2f0c-46da-93c9-ca020aa1758f"
}
````
#### Beispiel (Fachdaten)
```
eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.yTSVS7re6hZKO46aDriHrRFOyc5-
3TIIrvcKUf2qAfGdH7InufWPCrDyEnazSDI7HtOa5X2MU3iUnmmiEuP-Lef76xTPv2lmL4_lyhW5D8zq
7zbrIaIaVhtg7ekF1r9Oy9nLsEBQWLD4EWda2PfAibV7iQbOVMn1rVk4DzKtCykj5RSrH96i-lbPVFl-
Xw_E2G5XsL0gOHrdbAsjTF1h67bvh2hnojc9SH1GnlD0TlUO30n0GKLgC7tNNiLGtNrRo8ih3LUWYo-m
34Q6NGjaNTycHnWMYZzXHbIcBzYr6WLTsrB07rKXEyrHGLaRL88y2c-ACyEzpgv4qR5DAp98Su2u45ar
pfGU_7HxX4d-PLEoDfIRnh32nprarbaIesj9Ppgiu7QciWRApcyszk0a5rzZ7Dk_6-ydMfD92H2p3tdt
OcFhj3XGUshVKec2nRhtCZPOMPTIjxFpozsiRetjZo9LFHzRcvr1eSS_hpteKJ3ltioY9nzt1IX2JqQm
TGtY.VGOCnGM9LEZP5mUO.LQeKj4SKqsUNsBp4ZRN_56QbS8MQ01YTzRVFStk.Z0YMEua9kvCV7LkeJH
kprA
````
### encoding: plain
Bei der Übertragung der Fachdaten muss der passende Content-Type gesetzt werden, also "application/json" bzw. "application/xml". Alternativ ist "text/json" und "text/xml" auch zulässig. Bei der Übertragung der Anlage ist der in den Metadaten angegebene Datentyp (z.B. "application/pdf") zu verwenden.
#### Beispiel
```
PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications//data HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjM1ZTM2Nzk2LTM1NDAtNDUwMy1iYT...
{"test":true,"hello":"world"}
```
### encoding: base64
Bei der Übertragung der Fachdaten und Anlagen wird der Content-Type "text/plain" für Base64 verwendet.
#### Beispiel
```
PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications//data HTTP/1.1
Content-Type: text/plain
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjM1ZTM2Nzk2LTM1NDAtNDUwMy1iYT...
eyJ0ZXN0Ijp0cnVlLCJoZWxsbyI6IndvcmxkIn0K
```
### encoding: jwe
Bei der Übertragung der Fachdaten und Anlagen wird der Content-Type "application/jose" (Achtung: jose, nicht json) verwendet.
#### Beispiel
```
PUT /delivery-service-beta7/sender/destinations/e1009dea-d97e-4104-b389-bf653d8bd30e/applications//data HTTP/1.1
Content-Type: application/jose
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjM1ZTM2Nzk2LTM1NDAtNDUwMy1iYT...
eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.yTSVS7re6hZKO46aDriHrRFOyc5-
3TIIrvcKUf2qAfGdH7InufWPCrDyEnazSDI7HtOa5X2MU3iUnmmiEuP-Lef76xTPv2lmL4_lyhW5D8zq
7zbrIaIaVhtg7ekF1r9Oy9nLsEBQWLD4EWda2PfAibV7iQbOVMn1rVk4DzKtCykj5RSrH96i-lbPVFl-
Xw_E2G5XsL0gOHrdbAsjTF1h67bvh2hnojc9SH1GnlD0TlUO30n0GKLgC7tNNiLGtNrRo8ih3LUWYo-m
34Q6NGjaNTycHnWMYZzXHbIcBzYr6WLTsrB07rKXEyrHGLaRL88y2c-ACyEzpgv4qR5DAp98Su2u45ar
pfGU_7HxX4d-PLEoDfIRnh32nprarbaIesj9Ppgiu7QciWRApcyszk0a5rzZ7Dk_6-ydMfD92H2p3tdt
OcFhj3XGUshVKec2nRhtCZPOMPTIjxFpozsiRetjZo9LFHzRcvr1eSS_hpteKJ3ltioY9nzt1IX2JqQm
TGtY.VGOCnGM9LEZP5mUO.LQeKj4SKqsUNsBp4ZRN_56QbS8MQ01YTzRVFStk.Z0YMEua9kvCV7LkeJH
kprA
```
docs/Detailinformationen/Glossar.md deleted 100644 → 0
View file @ 1b6edfde
# Glossar
...
**Noch in Arbeit**
...
\ No newline at end of file
docs/Detailinformationen/OAuth.md deleted 100644 → 0
View file @ 1b6edfde
# OAuth Details
## API Aufruf mit wget
Sie können auch mit dem Kommandozeilentool "wget" testen. In diesem Beispiel wird die Liste aller Destinations abgerufen:
```bash
wget --quiet --output-document - \
--method GET \
--timeout=0 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 5eadf042ef434913a5724d5e5ce38bc0' \
'https://subscriber.fiep-poc.de/beta6/subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c/destinations'
```
## Manueller OAuth 2.0 Fluss
Ein Entwickler hat in der Regel keine OAuth 2.0 Funktion direkt zur Verfügung. Daher müssen die Schritte einzeln durchgeführt werden. Um Zugriff auf die APIs zu erhalten muss Ihr Client zuerst einen OAuth Zugriff machen, um mit “client_id“, “client_secret“ ein Zugriffs-Token zu erhalten.
Die URL für den OAuth Zugriff lautet:
https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken
Folgende Query Parameter sind dabei mitzugeben:
- grant_type: client_credentials (fix)
- client_id: c1bbee16-fae1-4dc1-b0c6-b75a02b359b0 (Beispiel)
- client_secret: 91e7f6dd-5567-456f-a8be-aac10237c4c8 (Beispiel)
- scope: subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage (Beispiel)
<!-- theme: warning -->
> **Hinweis zu den Token:**
> Für den Zugriff auf die beiden APIs sind zwei unterschiedliche Scopes erforderlich. Diese enthalten beide Ihre Anwender-ID und könnten beispielsweise wie folgt aussehen:
> - Für die Application Subscriber API: **subscriber-**c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage
> - Für die Application Sender API: **sender-**c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage
>
> Sie können beim holen des Access Token das richtige Scope einsetzen oder ein Token für beide Scopes/APIs beziehen. Dazu schreiben Sie beide Scopes mit einem Leerzeichen dazwischen hintereinander:
>
> `subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage sender-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage`
>
> ![Zwei Scopes](https://raw.githubusercontent.com/fiep-poc/assets/master/images/oauth/18_zwei_scopes.png)
>
> Bitte beachten Sie, dass Sie statt "c94ae37e-dcc5-345e-a530-8651bdfa5f2c" Ihre Anwender-ID einsetzen müssen.
Ein Aufruf mit dem Werkzeug "wget" sieht z.B. wie folgt aus:
```bash
wget --quiet --output-document - \
--method GET \
'https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken?grant_type=client_credentials&client_id=c1bbee16-fae1-4dc1-b0c6-b75a02b359b0&client_secret=91e7f6dd-5567-456f-a8be-aac10237c4c8&scope=subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage'
```
Alternativ kann der Request auch per POST durchgeführt werden:
```bash
wget --quiet --output-document - \
--post-data 'grant_type=client_credentials&client_id=c1bbee16-fae1-4dc1-b0c6-b75a02b359b0&client_secret=91e7f6dd-5567-456f-a8be-aac10237c4c8&scope=subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c:manage' \
'https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken'
```
Die Antwort sieht in etwa wie folgt aus:
```json
{
"access_token": "0bd226153b394d209a9d57bd7a42ee70",
"token_type": "Bearer",
"expires_in": 3600
}
```
Der Wert für "access_token" wird dann als Header Parameter "Authorization" zusammen mit dem Text "Bearer" verwendet.
Hier wieder ein Beispiel mit dem Tool "wget":
```bash
wget --quiet --output-document - \
--method GET \
--header 'Authorization: Bearer 0bd226153b394d209a9d57bd7a42ee70' \
'https://subscriber.fiep-poc.de/beta6/subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c/destinations'
```