From 7152c2c259287f8717321979cce06e6c2b719abd Mon Sep 17 00:00:00 2001
From: Andreas Huber <andreas.huber@fjd.de>
Date: Tue, 30 Jun 2020 10:49:48 +0200
Subject: [PATCH] Erste Schritte
---
docs/1_Getting_Started.md | 18 +--
docs/4_Authentifizierung_und_Autorisierung.md | 106 +-----------------
.../Begrenzung_von_Abrufen.md | 0
.../Detailinformationen/Callback.md | 0
.../Detailinformationen/Clients.md | 0
.../Detailinformationen/Glossar.md | 0
docs/Detailinformationen/OAuth.md | 78 +++++++++++++
docs/Detailinformationen/Postman.md | 22 ++++
.../OAuth.md" | 1 -
.../Postman.md" | 1 -
10 files changed, 114 insertions(+), 112 deletions(-)
rename "docs/Weiterf\303\274hrende Informationen/Begrenzung_von_Abrufen.md" => docs/Detailinformationen/Begrenzung_von_Abrufen.md (100%)
rename "docs/Weiterf\303\274hrende Informationen/Callback.md" => docs/Detailinformationen/Callback.md (100%)
rename "docs/Weiterf\303\274hrende Informationen/Clients.md" => docs/Detailinformationen/Clients.md (100%)
rename "docs/Weiterf\303\274hrende Informationen/Glossar.md" => docs/Detailinformationen/Glossar.md (100%)
create mode 100644 docs/Detailinformationen/OAuth.md
create mode 100644 docs/Detailinformationen/Postman.md
delete mode 100644 "docs/Weiterf\303\274hrende Informationen/OAuth.md"
delete mode 100644 "docs/Weiterf\303\274hrende Informationen/Postman.md"
diff --git a/docs/1_Getting_Started.md b/docs/1_Getting_Started.md
index 1d2129a6..929d51e0 100644
--- a/docs/1_Getting_Started.md
+++ b/docs/1_Getting_Started.md
@@ -2,19 +2,19 @@
<!-- theme: info -->
-> ## â‘
-> Registrieren Sie sich für einen Account, um einen Zugriff auf eine API zu bekommen. Im Rahmen der Registrierung bekommen Sie durch das System eine eindeutige ID (Beispiel-ID) mitgeteilt. Aus dieser Account-ID leiten sich mit einem entsprechenden Präfix die Sender-ID (Senderpräfix_Beispiel-ID) und Subscriber-ID (Subscriberpräfix_Beispiel-ID) ab. (Siehe [Link auf „Authentifizierung und Autorisierung“ Abschnitt / Unterseite für Registrierung eines Accounts])
+> ## â‘ Account registrieren
+> Registrieren Sie sich für einen Account, um einen Zugriff auf eine API zu bekommen. Im Rahmen der Registrierung bekommen Sie durch das System eine eindeutige ID (Beispiel-ID) mitgeteilt. Aus dieser Account-ID leiten sich mit einem entsprechenden Präfix die Sender-ID (Senderpräfix_Beispiel-ID) und Subscriber-ID (Subscriberpräfix_Beispiel-ID) ab. ➡ [Anwender Registrierung](./4_Authentifizierung_und_Autorisierung.md)
-> ## â‘¡
-> Für den Zugriff auf die API fügen Sie dem Account einen Client hinzu und vergeben Sie dem Client die entsprechenden Scopes. (Siehe [Link auf „Authentifizierung und Autorisierung“ Abschnitt / Unterseite für Clientanlage und Scope Vergabe].
+> ## â‘¡ Client anlegen
+> Für den Zugriff auf die API fügen Sie dem Account einen Client hinzu und vergeben Sie dem Client die entsprechenden Scopes. ➡ [Client registrieren](./4_Authentifizierung_und_Autorisierung.md#client-registrierung)
-> ## â‘¢
-> Für einen einfachen Einstieg zum Test der API können Sie folgende Postman Collection (Link auf die Collection) nutzen und mittels des Postman REST Clients die Anfragen an die API durchführen. (Für nähere Informationen zu Postman siehe https://www.postman.com/) Alternativ können Sie die Anfragen auch mittels eigener Anwendungen oder alternative REST Client durchführen. Falls Sie nur für die Sender oder Subscriber Seite entwickeln, nutzen sie den folgenden Vorschlag auf Basis Postman [Link auf Postman basierte Teststrategie als Unterseite von „Weiterführende Informationen“].
+> ## â‘¢ API ausprobieren
+> Für einen einfachen Einstieg zum Test der API können Sie folgende Postman Collection (Link auf die Collection) nutzen und mittels des Postman REST Clients die Anfragen an die API durchführen. (Für nähere Informationen zu Postman siehe https://www.postman.com/) Alternativ können Sie die Anfragen auch mittels eigener Anwendungen oder alternative REST Client durchführen. Falls Sie nur für die Sender oder Subscriber Seite entwickeln, nutzen sie den folgenden Vorschlag auf Basis Postman ➡ [Testen mit Postman](./Detailinformationen/Postman.md)
-> ## â‘£
-> 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 [Link auf „Authentifizierung und Autorisierung“ Abschnitt / Unterseite für Token Abruf].
+> ## â‘£ OAuth Token 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)
-> ## ⑤
+> ## ⑤ API nutzen
> Verweis auf die Ablage der Open API Spec im Original
> Abschließendes Beispiel eines API Abrufs mit Token Abruf und einem Beispiel unter Nutzung des Tokens.
diff --git a/docs/4_Authentifizierung_und_Autorisierung.md b/docs/4_Authentifizierung_und_Autorisierung.md
index 3bc2fa81..54dccbc7 100644
--- a/docs/4_Authentifizierung_und_Autorisierung.md
+++ b/docs/4_Authentifizierung_und_Autorisierung.md
@@ -46,7 +46,7 @@ Hier ein Beispiel einer solchen Email:
> Mit freundlichem Gruß
> Ihr FIT-Connect Team.
-## Client (Anwendung) Registrierung auf ein API
+## Client Registrierung
<!-- theme: warning -->
> **Hinweis:** Im Zuge der ersten Anmeldung empfehlen wir die Umstellung der Sprache auf Deutsch.
@@ -76,6 +76,10 @@ Nun erscheint der folgende Dialog:
Hier vergeben Sie einen Anwendungsnamen und eine Beschreibung. Die Angabe einer Umleitungs-URI ist optional.
+Haken Sie beiden APIs ("Source/Sender" und "Subscriber") an.
+
+<!-- theme: warning -->
+> **Achtung:** Zum Testen benötigen Sie Zugriff auf beide APIs. Achten Sie bitte darauf, im unteren Teil beide Haken zu setzen.
Mit dem Button "Token anfordern" lösen Sie die Erstellung der Anwendung (Client) und der für Sie gültigen Subscriber-ID (subscriber-id) und/oder Source/Sender-ID (source-id) aus. Diese Subscriber-ID wird für alle weiteren API Aufrufe benötigt.
@@ -133,103 +137,3 @@ Verfahrensschritte:
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.
-
-## Testverfahren mit dem Tool Postman
-
-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)
-- [Environment](https://raw.githubusercontent.com/fiep-poc/assets/master/postman/FIT-Connect.postman_environment.json)
-
-### API Aufruf mit Postman OAuth 2.0 Konfiguration
-
-Mit diesen Angaben können Sie das API z.B. via Postman nutzen. Dazu wählen sie zunächst den Bereich "Authorization" aus. Danach kann der Button "Get New Access Token" genutzt werden.
-
-
-
-
-
-
-
-Mit diesem Token kann das API erfolgreich aufgerufen werden.
-
-
-
-In diesem Beispiel wurde eine neue Destination angelegt.
-
-### 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`
->
-> 
->
-> 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'
-```
diff --git "a/docs/Weiterf\303\274hrende Informationen/Begrenzung_von_Abrufen.md" b/docs/Detailinformationen/Begrenzung_von_Abrufen.md
similarity index 100%
rename from "docs/Weiterf\303\274hrende Informationen/Begrenzung_von_Abrufen.md"
rename to docs/Detailinformationen/Begrenzung_von_Abrufen.md
diff --git "a/docs/Weiterf\303\274hrende Informationen/Callback.md" b/docs/Detailinformationen/Callback.md
similarity index 100%
rename from "docs/Weiterf\303\274hrende Informationen/Callback.md"
rename to docs/Detailinformationen/Callback.md
diff --git "a/docs/Weiterf\303\274hrende Informationen/Clients.md" b/docs/Detailinformationen/Clients.md
similarity index 100%
rename from "docs/Weiterf\303\274hrende Informationen/Clients.md"
rename to docs/Detailinformationen/Clients.md
diff --git "a/docs/Weiterf\303\274hrende Informationen/Glossar.md" b/docs/Detailinformationen/Glossar.md
similarity index 100%
rename from "docs/Weiterf\303\274hrende Informationen/Glossar.md"
rename to docs/Detailinformationen/Glossar.md
diff --git a/docs/Detailinformationen/OAuth.md b/docs/Detailinformationen/OAuth.md
new file mode 100644
index 00000000..e2cdb74c
--- /dev/null
+++ b/docs/Detailinformationen/OAuth.md
@@ -0,0 +1,78 @@
+# 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`
+>
+> 
+>
+> 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'
+```
diff --git a/docs/Detailinformationen/Postman.md b/docs/Detailinformationen/Postman.md
new file mode 100644
index 00000000..3a32dfeb
--- /dev/null
+++ b/docs/Detailinformationen/Postman.md
@@ -0,0 +1,22 @@
+# Testen mit Postman
+
+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)
+- [Environment](https://raw.githubusercontent.com/fiep-poc/assets/master/postman/FIT-Connect.postman_environment.json)
+
+## API Aufruf mit Postman OAuth 2.0 Konfiguration
+
+Mit diesen Angaben können Sie das API z.B. via Postman nutzen. Dazu wählen sie zunächst den Bereich "Authorization" aus. Danach kann der Button "Get New Access Token" genutzt werden.
+
+
+
+
+
+
+
+Mit diesem Token kann das API erfolgreich aufgerufen werden.
+
+
+
+In diesem Beispiel wurde eine neue Destination angelegt.
diff --git "a/docs/Weiterf\303\274hrende Informationen/OAuth.md" "b/docs/Weiterf\303\274hrende Informationen/OAuth.md"
deleted file mode 100644
index 35e8dc8a..00000000
--- "a/docs/Weiterf\303\274hrende Informationen/OAuth.md"
+++ /dev/null
@@ -1 +0,0 @@
-# OAuth Details
diff --git "a/docs/Weiterf\303\274hrende Informationen/Postman.md" "b/docs/Weiterf\303\274hrende Informationen/Postman.md"
deleted file mode 100644
index 2cec4e94..00000000
--- "a/docs/Weiterf\303\274hrende Informationen/Postman.md"
+++ /dev/null
@@ -1 +0,0 @@
-# Testen mit Postman
--
GitLab