Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- edpweb3:jwt_external [2024/12/19 16:11] – [Aufruf des Endpoints] admin
+++ edpweb3:jwt_external [2026/03/29 21:52] (aktuell) – WRAP-Tags entfernt (Plugin nicht verfügbar) tim
@@ Zeile 1: / Zeile 1: @@
-====== Anmeldung aus Drittsystemen ======
+====== Anmeldung aus Drittsystemen (JWT External) ======
-Zur Anbindung an Drittsysteme kann ein zusätzlicher JWT Endpoint genutzt werden. Hierbei ist es auch möglich, dass die Benutzeraccounts auf Ebene von EDP gar nicht vorhanden und angelegt sind.
+Zur Anbindung an Drittsysteme bietet edp:web einen zusätzlichen Anmelde-Endpoint. Über diesen können Benutzer direkt aus einem externen System heraus in edp:web angemeldet werden — ohne dass die Benutzeraccounts in EDP vorhanden sein müssen.
-Insbesondere bei größeren Organisationen kann dies hilfreich sein, um aus einem zentralen Drittsystem heraus die Anmeldung und Benutzerverwaltung zentral zu steuern.
+Dies ist insbesondere für größere Organisationen hilfreich, die eine zentrale Benutzerverwaltung betreiben und die Anmeldung an edp:web darüber steuern möchten.
-Dazu muss dieser zunächst innerhalb der lokalen Konfigurationsdatei aktiviert werden. Im Nachfolgenden ist die Konfiguration beschrieben.
+Die Authentifizierung erfolgt über ein **JSON Web Token (JWT)**, das vom Drittsystem erzeugt und kryptographisch signiert wird. edp:web prüft die Signatur und meldet den Benutzer mit den im Token enthaltenen Informationen an.
-===== Konfiguration =====
+===== Funktionsweise =====
+Der Anmeldevorgang läuft wie folgt ab:
+  - Das **Drittsystem** erzeugt ein JWT mit den Benutzerdaten (Name, Funktion, Rolle) und signiert es mit seinem **privaten Schlüssel**.
+  - Der Benutzer wird mit dem JWT an den edp:web-Endpoint **/jwt_ext** weitergeleitet.
+  - **edp:web** prüft die Signatur des Tokens mit dem hinterlegten **öffentlichen Schlüssel** des Drittsystems.
+  - Bei erfolgreicher Prüfung wird eine Sitzung erstellt und der Benutzer ist angemeldet.
+<code>
+Drittsystem                          edp:web
+     │                                  │
+     │  1. JWT erzeugen & signieren     │
+     │  2. Weiterleitung mit JWT ──────►│
+     │                                  │  3. Signatur prüfen (Public Key)
+     │                                  │  4. Sitzung erstellen
+     │         ◄─────── Angemeldet ─────│
+</code>
+===== Einrichtung =====
+==== 1. Schlüsselpaar erzeugen ====
+Die Authentifizierung basiert auf einem **RSA-Schlüsselpaar** (asymmetrische Verschlüsselung). Das Drittsystem signiert das JWT mit dem privaten Schlüssel, edp:web prüft die Signatur mit dem öffentlichen Schlüssel.
+Das Schlüsselpaar kann z.B. mit OpenSSL erzeugt werden:
+<code>
+openssl genrsa -out jwt_external_private.pem 2048
+openssl rsa -in jwt_external_private.pem -pubout -out jwt_external_public.pem
+</code>
+  * **jwt_external_private.pem** → Verbleibt beim Drittsystem (zum Signieren der Tokens)
+  * **jwt_external_public.pem** → Wird auf dem edp:web-Server hinterlegt (zum Prüfen der Tokens)
+**Wichtig:** //
+Der private Schlüssel darf nicht an Dritte weitergegeben werden und sollte ausschließlich auf dem Drittsystem gespeichert sein.
+//
+==== 2. Public Key auf dem Server hinterlegen ====
+Die Datei **jwt_external_public.pem** muss im Unterordner **keys/** des edp:web-Installationsverzeichnisses abgelegt werden:
+<code>
+edpweb/
+└── keys/
+    └── jwt_external_public.pem
+</code>
+==== 3. Konfiguration aktivieren ====
+In der **edpweb.ini** muss folgender Block ergänzt werden:
-In der edpweb.ini muss folgender Block ergänzt werden:
 <code>
 [JWT External]
 Aktiv=1
-;Angabe des Secrets für das JWT
-Secret=...
 </code>
-Innerhalb des erzeugten JWTs müssen folgende Claims im Payload enthalten sein:
+Nach der Änderung muss der edp:web-Dienst neu gestartet werden.
-  * **sub**: Hier wird der Benutzername angegeben, unter dem der Benutzer in EDP angemeldet wird.
+===== JWT-Format =====
-  * **funktion**: Die Funktion definiert den Funktionsnamen, mit dem der Benutzer in EDP Web angemeldet wird.
-  * **rolle**: Hier muss die jeweilige Benutzerrolle angegeben werden, mit der der Benutzer in EDP Web angemeldet wird. Üblicherweise wären das default, abschnitt oder abteilung.
-  * **ort**:  Wenn der Benutzer mit der Abteilungsrolle angemeldet wird, muss hier zusätzlich noch das Ortsfeld angegeben werden, also die Filterung des Einsatzzugriffs auf einen bestimmten Bereich.
-Die Gültigkeit des JWTs sollte nur wenige Sekunden betragen, da es nur einmalig für die Anmeldung genutzt wird. Die Konfiguration dazu erfolgt auf Ebene des Drittsystems.
+Das Drittsystem muss ein JWT im folgenden Format erzeugen:
-Bitte beachten Sie darauf, dass das Secret eine ausreichende Komplexität besitzt.
+==== Header ====
-===== Aufruf des Endpoints =====
+<code>
+{
+  "alg": "RS256",
+  "typ": "JWT"
+}
+</code>
-Wenn der Endpoint in der Konfiguration aktiviert wurde, ist er wie folgt erreichbar:
+Als Signaturalgorithmus wird ausschließlich **RS256** (RSA mit SHA-256) unterstützt.
+==== Payload (Claims) ====
-====Aufruf per HTTP GET ====
 <code>
-https://ip-adresse:port/jwt_ext?jwt={JWT}
+{
+  "sub": "mmueller",
+  "funktion": "EL1",
+  "rolle": "abteilung",
+  "ort": "Zentrale",
+  "exp": 1743350400
+}
 </code>
-An Stelle von {JWT} muss das JWT angegeben sein.
+^ Claim ^ Beschreibung ^ Pflicht ^
+| **sub** | Benutzername, unter dem der Benutzer in edp:web angemeldet wird | Ja |
+| **funktion** | Funktionsname, mit dem der Benutzer in edp:web arbeitet | Ja |
+| **rolle** | Benutzerrolle: **default**, **abschnitt** oder **abteilung** | Ja |
+| **ort** | Ortsfilter für den Einsatzzugriff (nur bei Rolle //abteilung// erforderlich) | Bedingt |
+| **exp** | Ablaufzeitpunkt des Tokens als Unix-Timestamp | Ja |
+**Tipp:** //
+Die Gültigkeit des Tokens sollte nur wenige Sekunden betragen, da es ausschließlich für den einmaligen Anmeldevorgang genutzt wird.
+//
+===== Aufruf des Endpoints =====
+==== Per HTTP GET ====
-==== Aufruf per HTTP POST ====
 <code>
-https://ip-adresse:port/jwt_ext
+https://<adresse>:<port>/jwt_ext?jwt=<TOKEN>
+</code>
-Header:
+Diese Variante eignet sich für eine einfache Weiterleitung aus dem Drittsystem heraus (z.B. als Link oder Redirect).
-...
-Authorization: Bearer {JWT}
+==== Per HTTP POST ====
+<code>
+POST https://<adresse>:<port>/jwt_ext
+Authorization: Bearer <TOKEN>
 </code>
-{JWT}
+===== Konfiguration anpassen =====
-===== Anpassung der Zuordnung der Claims =====
-Sollte die Bezeichnung der Claims anderslautend als o.g. sein, so kann in der edpweb.ini zudem unter [JWT External] noch folgendes ergänzt werden:
+==== Claim-Bezeichnungen ändern ====
+Falls das Drittsystem andere Bezeichnungen für die Claims verwendet, können diese in der **edpweb.ini** angepasst werden:
 <code>
 [JWT External]
 Aktiv=1
-;Angabe des Secrets für das JWT
-Secret=...
-;Bezeichnung des Claims für den Benutzernamen
 FieldUsername=sub
-;Bezeichnung des Claims für die Funktion
 FieldFunktion=funktion
-;Bezeichnung des Claims für die Benutzerrolle
 FieldUserlevel=rolle
-;Bezeichnung des Claims für das Ortsfeld (benötigt bei der Benutzerrolle abteilung)
 FieldOrt=ort
 </code>
+^ INI-Feld ^ Standard ^ Beschreibung ^
+| FieldUsername | sub | Claim-Name für den Benutzernamen |
+| FieldFunktion | funktion | Claim-Name für die Funktion |
+| FieldUserlevel | rolle | Claim-Name für die Benutzerrolle |
+| FieldOrt | ort | Claim-Name für das Ortsfeld |
+**Beispiel:** Verwendet das Drittsystem den Claim //role// statt //rolle//, genügt die Anpassung:
+<code>
+FieldUserlevel=role
+</code>
+===== Hinweise =====
+  * Jede externe Anmeldung belegt einen **Lizenzplatz**. Stellen Sie sicher, dass ausreichend Lizenzen vorhanden sind.
+  * Externe Tokens können nicht serverseitig widerrufen werden. Die Gültigkeit wird ausschließlich über den **exp**-Claim im Token gesteuert.
+  * Es wird ausschließlich der Algorithmus **RS256** unterstützt. Tokens mit anderen Algorithmen (z.B. HS256, ES256) werden abgelehnt.
+  * Der Benutzername wird auf maximal **20 Zeichen**, die Funktion auf maximal **24 Zeichen** gekürzt.