Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- edpweb3:jwt_external [2024/12/19 11:35] – 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.
-In der edpweb.ini muss folgender Block ergänzt werden:
 <code>
-[JWT External]
+Drittsystem                          edp:web
-Aktiv=1
+     │                                  │
-;Angabe des Secrets für das JWT
+     │  1. JWT erzeugen & signieren     │
-Secret=...
+     │  2. Weiterleitung mit JWT ──────►│
-;Bezeichnung des Claims für den Benutzernamen
+     │                                  │  3. Signatur prüfen (Public Key)
-FieldUsername=sub
+     │                                  │  4. Sitzung erstellen
-;Bezeichnung des Claims für die Funktion
+     │         ◄─────── Angemeldet ─────│
-FieldFunktion=funktion
+</code>
-;Bezeichnung des Claims für die Benutzerrolle
-FieldUserlevel=rolle
-;Bezeichnung des Claims für das Ortsfeld (benötigt bei der Benutzerrolle abteilung)
-FieldOrt=ort
+===== 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>
-Innerhalb des erzeugten JWTs müssen folgende Inhalte im Claim enthalten sein:
+  * **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)
-  * **sub**: Hier wird der Benutzername angegeben, unter dem der Benutzer in EDP angemeldet wird.
+**Wichtig:** //
+Der private Schlüssel darf nicht an Dritte weitergegeben werden und sollte ausschließlich auf dem Drittsystem gespeichert sein.
+//
-Funktion.
+==== 2. Public Key auf dem Server hinterlegen ====
-Die Funktion definiert den Funktionsnamen, mit dem der Benutzer in EDP Web angemeldet wird.
+Die Datei **jwt_external_public.pem** muss im Unterordner **keys/** des edp:web-Installationsverzeichnisses abgelegt werden:
-Benutzerrolle.
+<code>
+edpweb/
+└── keys/
+    └── jwt_external_public.pem
+</code>
-Hier muss die jeweilige Benutzerrolle angegeben werden, mit der der Benutzer in EDP Web angemeldet wird.
+==== 3. Konfiguration aktivieren ====
-Üblicherweise wären das Default, Abschnitt oder Abteilung.
+In der **edpweb.ini** muss folgender Block ergänzt werden:
-Weitere Informationen zu den Benutzerrollen finden Sie hier.
+<code>
+[JWT External]
+Aktiv=1
+</code>
-Ortsfeld.
+Nach der Änderung muss der edp:web-Dienst neu gestartet werden.
-Wenn der Benutzer mit der Abteilungsrolle angemeldet wird, muss hier zusätzlich noch das Ortsfeld angegeben werden.
+===== JWT-Format =====
-Sprich die Filterung des Einsatzzugriffs auf einen bestimmten Bereich.
+Das Drittsystem muss ein JWT im folgenden Format erzeugen:
-Weitere Informationen dazu finden Sie hier.
+==== Header ====
-Die Gültigkeit des JWTs sollte nur wenige Sekunden betragen, da es nur einmalig für die Anmeldung genutzt wird.
+<code>
+{
+  "alg": "RS256",
+  "typ": "JWT"
+}
+</code>
-Die Konfiguration dazu erfolgt auf Ebene des Drittsystems.
+Als Signaturalgorithmus wird ausschließlich **RS256** (RSA mit SHA-256) unterstützt.
-Zuordnung der Claims zu den Datenfeldern auf Ebene von EDP.
+==== Payload (Claims) ====
-Die jeweiligen Felder im GWT können über die Konfiguration zugeordnet werden.
+<code>
+{
+  "sub": "mmueller",
+  "funktion": "EL1",
+  "rolle": "abteilung",
+  "ort": "Zentrale",
+  "exp": 1743350400
+}
+</code>
-Wenn die Feldnamen die EDP erwartet, von denen des GWTs abweicht.
+^ 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 |
-Bitte beachten Sie darauf, dass das Secret eine ausreichende Komplexität besitzt.
+**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 =====
-Wenn der Endpoint in der Konfiguration aktiviert wurde, ist er wie folgt erreichbar:
+==== Per HTTP GET ====
+<code>
+https://<adresse>:<port>/jwt_ext?jwt=<TOKEN>
+</code>
+Diese Variante eignet sich für eine einfache Weiterleitung aus dem Drittsystem heraus (z.B. als Link oder Redirect).
+==== Per HTTP POST ====
+<code>
+POST https://<adresse>:<port>/jwt_ext
+Authorization: Bearer <TOKEN>
+</code>
+===== Konfiguration anpassen =====
+==== 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
+FieldUsername=sub
+FieldFunktion=funktion
+FieldUserlevel=rolle
+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>
-https://ip-adresse:port/jwt_ext?jwt=...
+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.