Move detail articles unchanged to a dedicated place to reference on

docs/details/authentication/applications.md

+# Authentifizierung von Fachanwendungen
+
+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
+
+Entweder:
+
+- Liste der [LeiKa-IDs](https://www.it-planungsrat.de/DE/Projekte/Anwendungen/LeiKaPlus/leiKaPlus.html) und [Amtlicher Gemeindeschlüssel](https://www.statistikportal.de/de/gemeindeverzeichnis)
+
+Oder:
+
+- Name und Bezeichung der angeboteten Leistungen, wenn diese nicht Teil des Leistungskataloges sind
+
+Außerdem
+
+- Der Public Key zur Verschlüsselung der Antragsdaten
+- Der Public Key der Fachanwendung zur Signaturprüfung
+- Callback Endpunkte
+- Referenzen zu allen von diesem Endpunkt unterstützen Schemas
+
+Nach anlegen einer Destination erhält die Behörde, die für die Destination verantwortlich ist die OAuth Client Credentials. Mit diesen kann sich das Fachverfahren authentifizieren und erhält dafür einen JWT. Mit diesem JWT ist dann ein Abruf der hinterlegten Anträge möglich
+
+<img src="/images/oauth/JWT-Konzept-Fachanwendung.png" alt="JWT Konzept" width="400" />
+
+### Anforderung an die JWT-Tokens
+
+Die vom Auth Server generierten JWTs müssen nach [RFC 7519](https://tools.ietf.org/html/rfc7519) über folgende Attribute verfügen:
+
+#### Header
+
+Entsprechend [RFC 7519 Abschnnitt 8](https://tools.ietf.org/html/rfc7519#section-8):
+
+| Feld | Inhalt | **Erläuterung**                           |
+| ---- | ------ | ----------------------------------------- |
+| typ  | JWT    | Es handelt sich um einen JWT.             |
+| alg  | RS512  | Der JWT verwendet RSASSA-PSS und SHA-512. |
+
+**Beispiel**
+
+```json
+{
+  "typ":"JWT",
+  "alg":"HS256"
+}
+```
+
+#### Body des User-JWT-Tokens
+
+Entsprechend den [standartisierten Feldern](http://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms):
+
+| Feld       | Inhalt                                | **Erläuterung**                                              |
+| ---------- | ------------------------------------- | ------------------------------------------------------------ |
+| iat        | Unix Timestamp                        | Zeitpunkt wann der Token ausgestellt wurde als Unix Timestamp. |
+| exp        | Unix Timestamp                        | Zeitpunkt wann der Token abläuft als Unix Timestamp (Token sollte max. 2 Stunden gültig sein vgl [BSI APP.3.1](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Grundschutz/Kompendium_Einzel_PDFs/06_APP_Anwendungen/APP_3_1_Webanwendungen_Edition_2020.pdf?__blob=publicationFile&v=1)). |
+| scope      | Liste von Zustellberechtigungs-Scopes | Eine Liste der Zustellberechtigungs-Scopes, für die der JWT einen Abruf erlaubt. |
+| clientType | subscriber                            | Gibt an, das es sich um einen Token für ein antragsempfangendes System (Fachanwendung oder virtuelle Poststelle) handelt. |
+
+**Beispiel**
+
+```json
+{
+  "iat":"1620072619",
+  "exp":"1620079819",
+  "scope": ["36141427-d405-40a4-8f8b-3592d544e85b", "655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1"],
+  "clientType": "subscriber"
+}
+
+```
+
+## Validierung der JWT-Tokens durch den Zustelldienst
+
+Beim Abruf am Zustelldienst muss dieser bzw. das API-Gateway überprüfen, ob der JWT-Token valide ist. Dafür sollten mindestes folgende Überprüfungen durchgeführt werden:
+
+1. Überprüfen, ob es sich um einen JWT mit einer **RSASSA-PSS (PS512)** Signatur handelt.
+2. Überprüfen, ob der JWT noch gültig ist.
+3. Überprüfen, ob der JWT für max. 4h ausgestellt wurde.
+3. Mithilfe des Public Keys des Authentifizierungsservers die Signatur des JWT überprüfen. 
+4. Überprüfen, ob die Destination-ID, die abgerufen werden soll teil der in den Zustellberechtigungs-Scopes (**scope** Parameter in den JWTs) des JWTs ist. (Zugangsberechtigung der Fachanwendung). 
+

docs/details/authentication/cli.md

+# Developer-CLI
+
+Im Folgenden wird beschrieben, wie die OAuth-basierte Authentifizierung mithilfe des FIT-Connect Commandline-Tools funktioniert. 
+Dafür werden entweder OAuth-Credentials (Client-ID, Client-Secret) sowie die Adresse des OAuth-Token-Endpunktes oder ein Zugang zum FIT-Connect Developer Portal benötigt. 
+Weitere Informationen dazu wie die OAuth-Authentifizierung selbst implementiert werden kann befinden sich in [Authentifizierung von Fachanwendungen](applications) und [Authentifizierung von Usern an Zustelldiensten](users) - außerdem ist hier das Konzept zu [Zustellberechtiungs-Scopes](scopes) zu beachten.
+
+## Installation CLI-Tool
+
+Das CLI-Tool kann über den Python Paketmanager pip installiert werden. Dafür muss Python 3.6 oder neuer installiert sein.
+
+```bash
+pip install fitconnect-cli
+```
+
+Nach der Installation von fitconnect-cli kann mithilfe des folgenden Kommandos eine neue FIT-Connect API-Konfiguration angelegt werden.
+
+```bash
+ fitconnect create_config --config=test_sender.json  
+```
+
+Hierbei muss ausgewählt werden, ob ein Sende- oder Empfangsdienst betrieben werden und ob automatisch RSA-Keys für die Generierung von JWTs angelegt werden sollen.
+
+```bash
+ fitconnect create_config --config=test_sender.json  
+? Do you want to setup a config for a sender (e.g. onlineservice) or receiver?  sender
+? Oauth Token URL:  https://fit-connect.de/oauth/token
+? Client id:  nnXVC6DSPG9BkoMw5NXOur4RPOkEpLMMwYFbycIo
+? Client secret:  Yj9PduOSsjGzwsIDXGRLrzDarZdKE4QPXuil21FqJGlVnZTDqcM7S5FruJA4kv1L3K4PCmAqAuK11y2fwu2MDVBiDUgWTBLc1e3H8tV0sD5PzlEiV7nCUAYBP7u8tG01
+? Do you want to create a jwt signature key?  yes
+-----BEGIN PUBLIC KEY-----
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAv6ixhhwQm8nTAAtgSBRP
+gNUuucb4e9Y0G2n8SBy4aEflIfrqKqqM1LRzLLnqvFiiiXI8heTx6AvMjQsqScHt
+0SDONWliz2s+lA80xyW+nJRKI/WUxXOZX0xqQD8XL6ZksE+nhZ9bKo7o5lXwQF6C
+p3BGV30kPgfGOCNPg4P5QpsP9UUfGvz1OXNNUPoMKovyXHAd7k4gI6TWZSqCbJwG
+3Y3v7WZKIb/1PGhkc7oR+SJ3t0jYJByRnhTyQAoMpODBlPz27/MOkozoNaAkjf6b
+pKcnasYCJHkuAcCS7pI5VZz7YNZPl3dm0g4woOsJeEdV2B2fyv4E0uYw2eRFsxlu
+/TdAid6UAf1fMz4JVoJ3dsca+1zySX7S4P+pVjNXQW0cGVO4hksvQSFwhBpnEAEw
+rHBdVV15UVT98cFEfhlv3utI6KdXJqpnWBm8g9K3tFSAoTNXz81XAnFnZgLqA4If
+bws0R7Zu8fXYMQuGS2APzhH4QWVcqrgWizzg0P39W0f+44DIUgc6LJ344Iog3f2j
+ix3WeKi/VrKfJCLCisZyDUJNze9WfWVersGVMsgnND84y9+EG2Pp/m99jF+asrDi
+gJa7FZjjoXRJVhTBcGQ1eW95G+Vm/oKkAp+unFBCqNtS610vQzviM147KtIvUrpj
+q1r1v0Vzj+qk9WEGVz/Gl4MCAwEAAQ==
+-----END PUBLIC KEY-----
+```
+
+Nachdem der Assistent abgeschlossen wurde, sollte im aktuellen Verzeichnis eine JSON-Datei mit allen benötigten Konfigurationen angelegt worden sein. Diese lässt sich nun mit einem FIT-Connect-API-Client oder dem fitconnect-cli weiterbenutzten.
+
+## Generierung von JWTs
+
+Mithilfe der fitconnect-cli können JWTs zum Abrufen von bzw. Versenden von Anträgen generiert werden. Dabei wird zuerst über das OAuth 2 Client Credentials Verfahren ein JWT abgerufen und dann falls Antreäge versendet werden sollen der sogenannte Online-Service-Token mit eingeschränkten Berechtigungen davon abgeleitet.
+
+### Abrufen von JWTs für antragssendene Systeme (Onlineservices)
+
+Für die Generierung von JWTs zum Versenden von Anträgen muss neben der Konfiguration außerdem über den Parameter *destination* angegeben werden, an welche Destination-IDs Anträge gesendet werden sollen. 
+
+```bash
+fitconnect get_jwt --config=test_sender.json --destination "d771f1d8-6967-4740-9668-82c5a910a29b"
+```
+
+Bei erfolgreicher Generierung erhält man ein JSON-Objekt mit einem User-Token und einen Online-Service-Token zurück. Diese können dann dazu verwendet werden um mithilfe eines  FIT-Connect-API-Client oder CURL einen Einreichung versenden. 
+
+```json
+{
+    "online-service-token": "..online-service-token...",
+    "token": "...token..."
+}
+```
+
+Der dekodierte Inhalt eines Online-Service-Tokens sieht z.B. so aus:
+
+```json
+{
+  "iss": "FITCONNECT",
+  "exp": 1623275003,
+  "iat": 1623260603,
+  "domains": [],
+  "publicKey": {
+    "n": "...RSA Token...",
+    "e": "AQAB",
+    "kty": "RSA"
+  },
+  "scope": [
+    "leika:991080082520",
+    "region:03254021",
+    "leika:991080082520+region:03254021"
+  ],
+  "clientType": "sender"
+}
+```
+
+Und der eines User-Tokens so:
+
+```json
+{
+  "iss": "Onlineservice",
+  "exp": 1623267803,
+  "iat": 1623260603,
+  "domains": [],
+  "scope": [
+    "destination:d771f1d8-6967-4740-9668-82c5a910a29b"
+  ],
+  "clientType": "user-sender"
+}
+```
+
+Ein CURL-Request um dann mit diesen Tokens auf die API zuzugreifen, könnte z.B. so aussehen:
+
+```bash
+curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "token: ...token..."  -H "online-service-token:  ...online-service-token..." https://fit-connect-url.einfügen
+```
+
+### Abrufen von JWTs für antragsempfangende Systeme (Fachverfahren / virtuelle Poststellen)
+
+Wenn ein JWT zum Abrufen von Anträgen generiert werden soll, kann auf den Parameter destination verzichtet werden.
+
+```bash
+fitconnect get_jwt --config=test_receiver.json 
+```
+
+Als Antwort erhält man einen (vom Authentifizierungsserver via OAuth Client Credentials abgerufenen) JWT, welchen man zur Authentifizierung beim Abrufen von Anträgen verwenden kann.
+
+```bash
+curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "token: ...token..."  https://fit-connect-url.einfügen
+```

docs/details/authentication/scopes.md

+# Zustellberechtigungs-Scope
+
+Die Zustellberechtigungs-Scopes erlauben dem Zustelldienst festzustellen, ob ein dort eingesendeter Einreichung vom Versender an eine Destination übermittelt werden darf.
+
+## Zusammensetzung der Zustellberechtigungs-Scopes
+
+Der Zustellberechtigungsscope kann entweder eine Destination-ID oder alternativ eine spzifische Art der Leistung, eine bestimmte Region oder eine Kombination aus Region und Leistung enthalten. Die Angabe im Scope beschränkt Zugriffe auf die angegeben Zustellpunkte, Leistungen oder Regionen. 
+
+Ein Zustellberechtigungs-Scope kann den folgenden Typen entsprechen:
+
+| Type           | Beispiel                                         | Erläuterung                                                  |
+| -------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| destination    | destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1 | Die UUID einer in FIT-Connenct angelegten Destination.       |
+| leika          | leika:99108008252000                             | LeiKa steht dafür, das die folgende ID einer Leistung im [Leistungskatalog der öffentlichen Verwaltung](https://leitfaden.ozg-umsetzung.de/display/OZG/2.1+Verwaltungsleistungen+im+Sinne+des+OZG) verzeichnet ist. |
+| region         | region:08110000                                  | Region steht für einen [Amtlichen Gemeindeschlüssel](https://de.wikipedia.org/wiki/Amtlicher_Gemeindeschl%C3%BCssel) |
+| region-leika   | region:08110000+leika:99108008252000             | Eine Kombination aus einem amtlichen Gemeindeschlüssel und einer LeiKa-ID. Hier erfolgt eine Einschränkung nach beiden angegeben Kriterien (Zugriff nur auf spezifische Leistung in der angegebenen Region). |
+| custom-service | custom-service:42                                | Eine Leistung, die nicht im Leistungskatalog abgebildet wird. |
+
+## Beispiele
+Beschränkung auf eine spezifische Destination:
+
+```
+destination:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1
+```
+
+Bei den Destinationen kann zusätzlich der Scope **destination:create** (erstellen der Destination) , **destination:manage** (verwalten der Destination) und **destination:subscribe** (subscriben auf Webhooks) vergeben werden.
+
+```
+destination:manage:655c6eb6-e80a-4d7b-a8d2-3f3250b6b9b1
+```
+
+LeiKa-Leistung für die [Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000):
+
+```
+leika:99108008252000
+```
+
+Wenn ein Prefix für einen AGS angegeben wird, schließt dieser alle sich darin befindlichen Subentitäten mit ein. Dieser Schlüssel steht für alle Leistungen in der Region Stuttgart und schließt alle darunterliegenden Gemeinden, Stadtteile, etc. mit ein:
+
+```
+region:08110000
+```
+
+Die LeiKa-Leistung für die [Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000) in der Region Stuttgart:
+
+```
+region:08110000+leika:99108008252000
+```
+
+## Kombination verschiedener Berechtigungen
+
+Wenn eine Liste von Zustellberechtigungsscopes angegeben wird, sind diese immer unabhängig voneinander zu betrachten. Im folgenden Fall werden sowohl alle Leistungen in der Region Stuttgart als auch die Leistung [Begutachung von abgeschleppten Fahrzeugen](https://fimportal.de/detail/L/99108008252000) in Brandenburg freigegeben:
+
+```json
+["region:08110000", "region:12000000+leika:99108008252000"]
+```
+
+## Regex zur Validierung
+
+```
+(leika:[0-9]{1,12})|(region:[0-9]{1,12})|(custom-service:[0-9]{1,12})|(destination(:create|:manage|:subscribe)?:[0-9A-F]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89AB][0-9a-f]{3}-[0-9a-f]{12})
+```
+