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.

Drittsystem                          edp:web
     │                                  │
     │  1. JWT erzeugen & signieren     │
     │  2. Weiterleitung mit JWT ──────►│
     │                                  │  3. Signatur prüfen (Public Key)
     │                                  │  4. Sitzung erstellen
     │         ◄─────── Angemeldet ─────│

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:

openssl genrsa -out jwt_external_private.pem 2048
openssl rsa -in jwt_external_private.pem -pubout -out jwt_external_public.pem

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:

edpweb/
└── keys/
    └── jwt_external_public.pem

3. Konfiguration aktivieren

In der edpweb.ini muss folgender Block ergänzt werden:

[JWT External]
Aktiv=1

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

JWT-Format

Das Drittsystem muss ein JWT im folgenden Format erzeugen:

{
  "alg": "RS256",
  "typ": "JWT"
}

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

Payload (Claims)

{
  "sub": "mmueller",
  "funktion": "EL1",
  "rolle": "abteilung",
  "ort": "Zentrale",
  "exp": 1743350400
}

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

https://<adresse>:<port>/jwt_ext?jwt=<TOKEN>

Diese Variante eignet sich für eine einfache Weiterleitung aus dem Drittsystem heraus (z.B. als Link oder Redirect).

Per HTTP POST

POST https://<adresse>:<port>/jwt_ext
Authorization: Bearer <TOKEN>

Konfiguration anpassen

Claim-Bezeichnungen ändern

Falls das Drittsystem andere Bezeichnungen für die Claims verwendet, können diese in der edpweb.ini angepasst werden:

[JWT External]
Aktiv=1
FieldUsername=sub
FieldFunktion=funktion
FieldUserlevel=rolle
FieldOrt=ort

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:

FieldUserlevel=role

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.

edp:dokuwiki