From 5c039b61d183efa9973d89ab1b32b9be8fc34610 Mon Sep 17 00:00:00 2001
From: Lilith Wittmann <mail@lilithwittmann.de>
Date: Wed, 9 Jun 2021 19:23:33 +0200
Subject: [PATCH] feat(oauth): Explain how to use the fitconnect cli to get
oauth tokens
---
docs/Detailinformationen/OAuth.md | 81 +++++++++++--------------------
1 file changed, 28 insertions(+), 53 deletions(-)
diff --git a/docs/Detailinformationen/OAuth.md b/docs/Detailinformationen/OAuth.md
index e2cdb74c..2efa8c23 100644
--- a/docs/Detailinformationen/OAuth.md
+++ b/docs/Detailinformationen/OAuth.md
@@ -1,78 +1,53 @@
-# OAuth Details
+# OAuth Authentifizierung
-## API Aufruf mit wget
+Das folgende Dokument beschreibt 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 und Authentifizierung von Authentifizierung von Usern an Zustelldiensten - außerdem ist hier das Konzept zu Zustellberechtiungs-Scopes zu beachten.
-Sie können auch mit dem Kommandozeilentool "wget" testen. In diesem Beispiel wird die Liste aller Destinations abgerufen:
+## 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
-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'
+pip install fitconnect-cli
```
-## Manueller OAuth 2.0 Fluss
+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
+```
-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.
+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.
-Die URL für den OAuth Zugriff lautet:
-https://oauth.fiep-poc.de/invoke/pub.apigateway.oauth2/getAccessToken
+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.
-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)
+## Generierung von JWTs
-<!-- 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`
->
-> 
->
-> Bitte beachten Sie, dass Sie statt "c94ae37e-dcc5-345e-a530-8651bdfa5f2c" Ihre Anwender-ID einsetzen müssen.
+Mithilfe des fitconnect-cli können JWTs zum Abrufen von bzw. Versenden von Anträgen generiert werden.
-Ein Aufruf mit dem Werkzeug "wget" sieht z.B. wie folgt aus:
+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
-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'
+fitconnect get_jwt --config=test_sender.json --destination "d771f1d8-6967-4740-9668-82c5a910a29b"
```
-Alternativ kann der Request auch per POST durchgeführt werden:
+Bei erfolgreicher Generierung erhält man ein JSON-Objekt mit einem 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 Antrag versenden.
+
+Ein CURL-Request dafür könnte z.B. so aussehen:
```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'
+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
```
-Die Antwort sieht in etwa wie folgt aus:
+Wenn ein JWT zum Abrufen von Anterägen generiert werden soll, kann auf den Parameter destination verzichtet werden.
-```json
-{
- "access_token": "0bd226153b394d209a9d57bd7a42ee70",
- "token_type": "Bearer",
- "expires_in": 3600
-}
+```bash
+fitconnect get_jwt --config=test_receiver.json
```
-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":
+Bei erfolgreicher Generierung erhält man einen JWT Token, welchen man zur Authentifizierung gbeim Abrufen von Anträgen verwenden kann
```bash
-wget --quiet --output-document - \
- --method GET \
- --header 'Authorization: Bearer 0bd226153b394d209a9d57bd7a42ee70' \
- 'https://subscriber.fiep-poc.de/beta6/subscriber-c94ae37e-dcc5-345e-a530-8651bdfa5f2c/destinations'
+curl -i -H "Accept: application/json" -H "Content-Type: application/json" -H "token: ...token..." https://fit-connect-url.einfügen
```
+
+
--
GitLab