Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT

Aus OBS Wiki

Anmeldung mit JWT

Mit der JWT-Anmeldung melden sich die Benutzer einer App oder eines Portals einzeln am REST-Server an und erhalten ein zeitlich begrenztes Token. Sie ist nötig, sobald ein Zugang nicht nur den Client, sondern auch den Menschen dahinter kennen soll. Diese Seite beschreibt den ganzen Ablauf für Entwickler von Client und Anmeldeskript.

Überblick

Alle Token-Vorgänge laufen über einen einzigen Pfad, den JWT-Endpunkt des Zugangs:

  1. Anmelden: Der Client sendet die Anmeldedaten ohne Authorization-Header an den JWT-Endpunkt. Das Anmeldeskript prüft sie, der Server stellt ein Access-Token und auf Wunsch ein Refresh-Token aus.
  2. Aufrufen: Jeder weitere Aufruf trägt das Access-Token im Header Authorization: Bearer ….
  3. Erneuern: Läuft das Access-Token ab, legt der Client das Refresh-Token am JWT-Endpunkt vor und erhält ein neues Paar.
  4. Abmelden: Ein DELETE mit dem Access-Token an den JWT-Endpunkt beendet die Sitzung.
Token Wofür Laufzeit
Access-Token jeder Aufruf eines Endpunkts, Abmelden Lebenszeit (Min) des Zugangs
Refresh-Token nur Erneuern am JWT-Endpunkt vom Anmeldeskript bestimmt, Standard 90 Tage, höchstens 372 Tage

Jede Anmeldung eröffnet eine Sitzung. Erneuerte Token bleiben in derselben Sitzung, das Abmelden sperrt sie als Ganzes. Die Token sind mit dem Secret-Key des Zugangs signiert (HS256, Aussteller OBS REST-Server).

Der API-Key im Header apikey gehört weiterhin zu jeder Anfrage, auch zur Anmeldung. Den allgemeinen Aufbau von Anfragen und Fehlerantworten beschreibt HTTP-Schnittstelle.

Einrichtung in OBS

Die JWT-Anmeldung wird je Zugang eingerichtet. Setzen Sie in der Eingabemaske des Zugangs den Haken JWT-Authentifizierung und füllen Sie die Felder daneben:

Feld Bedeutung
Endpunkt Pfad des JWT-Endpunkts, z.B. /service/auth. Groß- und Kleinschreibung sowie ein abschließender Schrägstrich spielen keine Rolle.
Secret-Key Schlüssel für die Signatur. Ein neuer Secret-Key macht alle ausgegebenen Token ungültig.
Lebenszeit (Min) Laufzeit des Access-Tokens in Minuten.
  • Das Anmeldeskript bearbeiten Sie in der Zugänge-Liste mit F7.
  • Der JWT-Endpunkt braucht keinen eigenen Eintrag unter den Endpunkten und keine Berechtigung. Der Server erkennt ihn vor der Adressauflösung.
  • Die Sitzungen stehen in der Tabelle RESTSRV_TOKEN. Sie entsteht beim Datenbankabgleich. Fehlt sie, stellt der Server kein Token aus.

Ist JWT-Authentifizierung gesetzt, verlangt jeder andere Pfad dieses Zugangs ein gültiges Access-Token. Details zu den übrigen Feldern: Zugänge.

Anmelden

Eine Anfrage an den JWT-Endpunkt ohne Authorization-Header ist eine Anmeldung. Senden Sie sie als POST. Welche Felder der Körper enthält, bestimmt das Anmeldeskript; üblich sind Benutzername und Passwort. Ein Idempotency-Key ist am JWT-Endpunkt nicht nötig.

POST /service/auth
apikey: <API-Key>
Content-Type: application/json

{"username": "<Benutzer>", "password": "<Passwort>"}

Bei Erfolg antwortet der Server mit 200:

{
  "benutzerId": "4711",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 28800,
  "serverTime": "2026-11-17T09:12:33+01:00"
}
Feld Inhalt
token, accessToken dasselbe Access-Token unter zwei Namen
refreshToken Refresh-Token. Nur vorhanden, wenn das Anmeldeskript eines anfordert.
expiresIn Laufzeit des Access-Tokens in Sekunden (Lebenszeit (Min) × 60)
serverTime Uhrzeit des Servers nach ISO 8601 mit UTC-Offset
weitere Felder alles, was das Anmeldeskript zusätzlich schreibt, im Beispiel benutzerId. So erhält der Client Benutzerangaben ohne zweiten Aufruf.

Eine abgelehnte Anmeldung beantwortet der Server mit 401 und dem Code AUTH_FAILED. Die message ist der Text aus dem Anmeldeskript und kann dem Benutzer direkt angezeigt werden:

{"error": {"code": "AUTH_FAILED", "uid": "<uid>", "message": "Benutzer oder Passwort ist falsch", "traceId": "<traceId>"}}

Ein falsches Passwort zählt beim Rate-Limit nicht als Fehlanfrage. Weitere Fehlerfälle stehen unter Fehlerfälle.

Geschützte Endpunkte aufrufen

Jeder Aufruf trägt das Access-Token:

GET /service/orders
apikey: <API-Key>
Authorization: Bearer <accessToken>

Schreiben Sie Bearer genau so, mit großem B und einem Leerzeichen danach.

Der Server prüft Signatur, Aussteller, Ausstellzeit und Ablauf mit seiner eigenen Uhr und lässt 20 Sekunden Abweichung zu. Danach prüft er, ob die Sitzung noch offen ist. Ein Abmelden wirkt damit sofort.

  • Fehlt das Token, antwortet der Server mit 401 AUTH_REQUIRED. Das gilt auch für einen unbekannten Pfad, weil die Prüfung vor der Adressauflösung liegt.
  • Ist das Token abgelaufen, ungültig oder seine Sitzung gesperrt, antwortet er mit 401 AUTH_EXPIRED. Erneuern Sie dann das Token.
  • Wurde die Lebenszeit (Min) verkürzt, weist der Server Access-Token ab, deren Restlaufzeit über der neuen Lebenszeit liegt.

Berechnen Sie den Zeitpunkt der Erneuerung aus expiresIn ab Erhalt der Antwort. serverTime zeigt Ihnen, wie weit die Uhr des Geräts von der des Servers abweicht.

Token erneuern

Zum Erneuern legt der Client das Refresh-Token am JWT-Endpunkt vor. Jedes Verb außer DELETE gilt als Erneuern; verwenden Sie POST. Ein Körper ist nicht nötig.

POST /service/auth
apikey: <API-Key>
Authorization: Bearer <refreshToken>

Die Antwort hat denselben Aufbau wie bei der Anmeldung und enthält ein neues Paar in derselben Sitzung. Speichern Sie beide Token.

  • Einmalgebrauch: Der Server entwertet das vorgelegte Refresh-Token, bevor das Anmeldeskript läuft. Ein zweites Vorlegen wird abgewiesen.
  • Gleichzeitiges Erneuern: Legt der Client dasselbe Refresh-Token innerhalb von 60 Sekunden erneut vor, antwortet der Server mit 401 AUTH_EXPIRED, die Sitzung bleibt offen. Später gilt es als Wiedervorlage eines kopierten Tokens: Der Server sperrt die ganze Sitzung.
  • Ablehnung durch das Skript: Lehnt das Anmeldeskript die Erneuerung ab, antwortet der Server mit 401 AUTH_EXPIRED und einer allgemeinen Meldung. Der Text des Skripts steht nur im Protokoll.
  • Bisherige Access-Token bleiben bis zu ihrem Ablauf gültig. Parallel laufende Anfragen scheitern also nicht am Erneuern.

Empfehlung für den Client:

  1. Erneuern Sie nur einmal gleichzeitig. Weitere Anfragen, die in 401 AUTH_EXPIRED laufen, warten auf das Ergebnis und verwenden dann das neue Access-Token.
  2. Antwortet das Erneuern mit 401, legen Sie die Anmeldemaske vor.
  3. Enthält die Antwort kein refreshToken, melden Sie sich nach Ablauf des Access-Tokens neu an.

Abmelden

Abgemeldet wird mit einem DELETE und dem Access-Token am JWT-Endpunkt:

DELETE /service/auth
apikey: <API-Key>
Authorization: Bearer <accessToken>

Der Server antwortet mit 204 ohne Körper und sperrt die ganze Sitzung, also auch die Access-Token früherer Erneuerungen und das Refresh-Token. Das Anmeldeskript wird dabei nicht aufgerufen.

  • Ein wiederholtes Abmelden bleibt erfolgreich (204).
  • Lässt sich die Sitzung nicht sperren, antwortet der Server mit 503 und Retry-After. Der Client ist dann nicht abgemeldet und wiederholt den Aufruf.
  • Mit dem Refresh-Token statt des Access-Tokens antwortet der Server mit 401 AUTH_FAILED.
  • Ist das Access-Token schon abgelaufen, antwortet der Server mit 401 AUTH_EXPIRED. Erneuern Sie es zuerst und melden Sie sich dann ab. Sonst bleibt das Refresh-Token bis zu seinem Ablauf gültig.

Abmelden aus einem Endpunkt

Soll beim Abmelden zusätzlich etwas geschehen, etwa eine Geräteregistrierung gelöscht werden, oder sollen alle Geräte eines Benutzers abgemeldet werden, ruft ein gewöhnliches Endpunkt-Skript oWriter.JwtRevoke:

Aufruf Wirkung
oWriter.JwtRevoke('session') sperrt die Sitzung des vorgelegten Tokens
oWriter.JwtRevoke('all') sperrt alle Sitzungen desselben Subjects am selben Zugang. Setzt voraus, dass das Anmeldeskript _OBS_JWT_SUBJECT geschrieben hat.
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
    // Fachliche Aufgaben beim Abmelden, z.B. Geräteregistrierung löschen
    oWriter.JwtRevoke('all');
    oWriter.Status(204);
    oWriter.NoBody();
end;

Lässt sich die Sperre nicht schreiben, ersetzt der Server die Antwort des Skripts durch 503 mit Retry-After. Bei 'all' gilt das auch, wenn das Token kein Subject trägt.

Das Anmeldeskript

Das Anmeldeskript des Zugangs (F7 in der Zugänge-Liste) enthält zwei Methoden mit derselben Signatur wie jede Endpunkt-Methode:

procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
  • Authenticate läuft bei der Anmeldung. Der Körper der Anfrage steht im Reader.
  • Refresh läuft beim Erneuern, nachdem der Server das Refresh-Token geprüft und entwertet hat. Die Werte des alten Tokens stehen im Reader (siehe Claims im Endpunkt lesen). Wer kein Refresh-Token ausstellt, braucht diese Methode nicht.

Fehlt die aufgerufene Methode, antwortet der Server mit 405. Reader und Writer allgemein: Scripting.

Rückgabe

Beide Methoden schreiben ihr Ergebnis als Felder in den Writer:

Feld Bedeutung
status 1 = Token ausstellen, 9 = ablehnen. Pflicht.
error Text der Ablehnung bei 9. Bei der Anmeldung geht er an den Client, beim Erneuern nur ins Protokoll.
_OBS_JWT_SUBJECT Subject (sub), üblich der Benutzername. Nötig für JwtRevoke('all').
_OBS_JWT_ID Token-ID (jti), z.B. die Benutzernummer. Muss nicht eindeutig sein.
_OBS_JWT_AUDIENCE Audience (aud), z.B. eine Anwendung oder Gruppe
_OBS_JWT_CLAIM_<name> eigener Claim <name>, z.B. _OBS_JWT_CLAIM_tenant. Der Wert wird als Text in das Token übernommen.
_OBS_JWT_REFRESH_ID fordert ein Refresh-Token an. Der Wert ist dessen Token-ID, z.B. GlobalUID().
_OBS_JWT_REFRESH_EXP Laufzeit des Refresh-Tokens in Minuten. Fehlt der Wert, gelten 90 Tage (129600). Wählen Sie höchstens 372 Tage (535680): Ein Refresh-Token mit längerer Restlaufzeit weist der Server beim Erneuern ab.
alle übrigen Felder gehen bei Erfolg unverändert in die Antwort an den Client
  • Felder mit _OBS_ und status gehen nicht an den Client. Felder namens token, accessToken, refreshToken, expiresIn und serverTime setzt der Server selbst.
  • Die Claims sid, rid und token_use setzt der Server. Verwenden Sie diese Namen und die Standardnamen (iss, sub, aud, exp, iat, jti, nbf) nicht für eigene Claims.
  • Ein anderer Status als 1 oder 9, ein Skriptfehler oder eine Antwort ohne status führt bei der Anmeldung zu 403. Ein defektes Skript erscheint dem Benutzer so nicht als falsches Passwort.
  • Beim Erneuern gelten Subject, Token-ID und Audience des alten Tokens weiter, wenn Refresh sie nicht neu schreibt. Eigene Claims und _OBS_JWT_REFRESH_ID müssen dagegen neu geschrieben werden. Ohne _OBS_JWT_REFRESH_ID enthält die Antwort kein neues Refresh-Token.
HINWEIS: Lesen Sie Rollen und Mandant in Refresh neu aus der Datenbank. Dann wirkt ein Entzug von Rechten spätestens mit der nächsten Erneuerung.

Beispiel

Tabelle, Felder und HashPasswort stehen für Ihre eigene Prüfung. Der Abfragetyp für DB_SOpen ist TxFQuery.

// Schreibt die Token-Felder eines gefundenen Benutzers
procedure TokenFelder(oWriter: TxRestWriter; qUser: TxFQuery);
begin
    oWriter.Int('status'               , 1);
    oWriter.Str('_OBS_JWT_ID'          , qUser.A2C('ab_nr'));
    oWriter.Str('_OBS_JWT_SUBJECT'     , qUser.A2C('ab_login'));
    oWriter.Str('_OBS_JWT_CLAIM_tenant', qUser.A2C('ab_mandant'));
    oWriter.Str('_OBS_JWT_REFRESH_ID'  , GlobalUID());
    oWriter.Str('benutzerId'           , qUser.A2C('ab_nr'));
end;

procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
    cPass: string;
    cSql : string;
    qUser: TxFQuery;
    lOk  : Boolean;
begin
    cUser := '';
    cPass := '';
    oReader.Str('username', cUser);
    oReader.Str('password', cPass);

    cSql := 'SELECT ab_nr, ab_login, ab_mandant FROM APP_BENUTZER' +
            ' WHERE ab_login = ' + DB_SQLVal(cUser) +
            '   AND ab_hash = '  + DB_SQLVal(HashPasswort(cPass)) +
            '   AND ab_aktiv = ' + DB_SQLVal('1');

    // DB_SOpen meldet nur, dass die Abfrage lief. Gefunden ist erst bei not EoF.
    lOk := false;
    if (DB_SOpen(oDB, cSql, qUser)) then begin
        if (not qUser.EoF) then begin
            lOk := true;
            TokenFelder(oWriter, qUser);
        end;
    end;
    DB_Close(qUser);

    if (not lOk) then begin
        oWriter.Int('status', 9);
        oWriter.Str('error' , 'Benutzer oder Passwort ist falsch');
    end;
end;

procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
    qUser: TxFQuery;
    lOk  : Boolean;
begin
    // Benutzer und Rechte neu lesen, nicht aus dem alten Token übernehmen
    cSql := 'SELECT ab_nr, ab_login, ab_mandant FROM APP_BENUTZER' +
            ' WHERE ab_login = ' + DB_SQLVal(oReader.Subject()) +
            '   AND ab_aktiv = ' + DB_SQLVal('1');

    lOk := false;
    if (DB_SOpen(oDB, cSql, qUser)) then begin
        if (not qUser.EoF) then begin
            lOk := true;
            TokenFelder(oWriter, qUser);
        end;
    end;
    DB_Close(qUser);

    if (not lOk) then begin
        oWriter.Int('status', 9);
        oWriter.Str('error' , 'Benutzer nicht mehr aktiv');
    end;
end;

Die Benutzernummer in _OBS_JWT_ID ist bei jeder Anmeldung gleich. Das ist zulässig: Der Server führt die Sitzungen über eigene Kennungen. Mehrere Anmeldungen desselben Benutzers sind deshalb möglich.

Claims im Endpunkt lesen

In jedem Endpunkt-Skript eines Zugangs mit JWT-Anmeldung stehen die Werte des vorgelegten Tokens im Reader:

Zugriff Inhalt
oReader.Subject() Subject (sub)
oReader.Param('_OBS_JWT_ID') Token-ID (jti)
oReader.Param('_OBS_JWT_AUDIENCE') Audience (aud)
oReader.Claim('<name>') eigener Claim, z.B. oReader.Claim('tenant'). Der Wert ist Text.
oReader.Claim('sid') Kennung der Sitzung; bleibt über alle Erneuerungen gleich
oReader.Claim('rid') Kennung des Token-Paares; bei jeder Erneuerung neu
oReader.Param('_OBS_JWT_EXP_SEC') Lebenszeit des Access-Tokens in Sekunden, derselbe Wert wie expiresIn

Namen mit _OBS_ kann ein Client weder über Header noch über Query-Parameter setzen. Lesen Sie Mandant und Rollen deshalb immer aus dem Token, nie aus Körper oder Query.

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cMandant: string;
begin
    cMandant := oReader.Claim('tenant');
    if (Empty(cMandant)) then begin
        oWriter.Error(403, 'FORBIDDEN_ROLE', 'Kein Mandant im Token');
        exit;
    end;
    // ... Daten des Mandanten lesen und schreiben
end;

Fehlerfälle

Nur die Fälle der JWT-Anmeldung. Alle Fehlerantworten haben das Format aus HTTP-Schnittstelle. Reagieren Sie auf code, nicht auf message.

Situation Status code Reaktion des Clients
Anmeldung vom Skript abgelehnt (status 9) 401 AUTH_FAILED message anzeigen, Anmeldemaske erneut vorlegen
Anmeldeskript fehlerhaft oder ohne gültigen Status 403 FORBIDDEN_ROLE nicht wiederholen, Support informieren
Methode Authenticate oder Refresh fehlt 405 METHOD_NOT_ALLOWED nicht wiederholen, Support informieren
Sitzung lässt sich bei der Ausstellung nicht speichern 503 SERVICE_UNAVAILABLE Anmeldung nach Retry-After wiederholen; beim Erneuern neu anmelden
Aufruf ohne Token 401 AUTH_REQUIRED Token mitsenden bzw. anmelden
Access-Token abgelaufen, ungültig oder Sitzung gesperrt 401 AUTH_EXPIRED Token erneuern
Refresh-Token an einem anderen Endpunkt 401 AUTH_FAILED, bei längerer Laufzeit als die Lebenszeit (Min) AUTH_EXPIRED Access-Token verwenden
Access-Token zum Erneuern vorgelegt 401 AUTH_FAILED Refresh-Token verwenden
Refresh-Token verbraucht, abgelaufen, ungültig oder Sitzung gesperrt 401 AUTH_EXPIRED neu anmelden
Erneuern vom Skript abgelehnt 401 AUTH_EXPIRED neu anmelden
Authorization: Bearer ohne Token am JWT-Endpunkt 401 AUTH_REQUIRED Token mitsenden
Refresh-Token zum Abmelden vorgelegt 401 AUTH_FAILED Access-Token verwenden
Sitzung lässt sich beim Abmelden nicht sperren 503 SERVICE_UNAVAILABLE nach Retry-After wiederholen

Die Gründe der Abweisungen stehen im Protokoll; die traceId der Antwort führt zur passenden Zeile. Siehe Betrieb und Fehlersuche.

Siehe auch