====== Anmeldung aus Drittsystemen (JWT External) ======

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.

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.

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.

===== 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:

<code>
[JWT External]
Aktiv=1
</code>

Nach der Änderung muss der edp:web-Dienst neu gestartet werden.

===== JWT-Format =====

Das Drittsystem muss ein JWT im folgenden Format erzeugen:

==== Header ====

<code>
{
  "alg": "RS256",
  "typ": "JWT"
}
</code>

Als Signaturalgorithmus wird ausschließlich **RS256** (RSA mit SHA-256) unterstützt.

==== Payload (Claims) ====

<code>
{
  "sub": "mmueller",
  "funktion": "EL1",
  "rolle": "abteilung",
  "ort": "Zentrale",
  "exp": 1743350400
}
</code>

^ 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 ====

<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>
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.