OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT: Unterschied zwischen den Versionen
Neue Seite: JWT-Lebenszyklus (Anmelden, Aufrufen, Erneuern, Abmelden), Anmeldeskript und Fehlerfälle [Styleguide-Abweichung: Linkziele folgen in derselben Welle] |
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt] |
||
| (Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt) | |||
| Zeile 23: | Zeile 23: | ||
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 <code>OBS REST-Server</code>). | 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 <code>OBS REST-Server</code>). | ||
Der API-Key im Header <code>apikey</code> gehört weiterhin zu jeder Anfrage, auch zur Anmeldung. Den allgemeinen Aufbau von Anfragen und Fehlerantworten beschreibt [[OBS/Kostenpflichtige Module/ | Der API-Key im Header <code>apikey</code> gehört weiterhin zu jeder Anfrage, auch zur Anmeldung. Den allgemeinen Aufbau von Anfragen und Fehlerantworten beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]. | ||
== Einrichtung in OBS == | == Einrichtung in OBS == | ||
| Zeile 42: | Zeile 42: | ||
* Die Sitzungen stehen in der Tabelle <code>RESTSRV_TOKEN</code>. Sie entsteht beim Datenbankabgleich. Fehlt sie, stellt der Server kein Token aus. | * Die Sitzungen stehen in der Tabelle <code>RESTSRV_TOKEN</code>. 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: [[OBS/Kostenpflichtige Module/ | Ist '''JWT-Authentifizierung''' gesetzt, verlangt jeder andere Pfad dieses Zugangs ein gültiges Access-Token. Details zu den übrigen Feldern: [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]]. | ||
== Anmelden == | == Anmelden == | ||
| Zeile 160: | Zeile 160: | ||
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter); | procedure Post(oReader: TxRestReader; oWriter: TxRestWriter); | ||
begin | begin | ||
// Fachliche Aufgaben beim Abmelden, z.B. | // Fachliche Aufgaben beim Abmelden, z.B. Geräteregistrierung löschen | ||
oWriter.JwtRevoke('all'); | oWriter.JwtRevoke('all'); | ||
oWriter.Status(204); | oWriter.Status(204); | ||
| Zeile 180: | Zeile 180: | ||
* <code>Refresh</code> 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|Claims im Endpunkt lesen]]). Wer kein Refresh-Token ausstellt, braucht diese Methode nicht. | * <code>Refresh</code> 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|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: [[OBS/Kostenpflichtige Module/ | Fehlt die aufgerufene Methode, antwortet der Server mit 405. Reader und Writer allgemein: [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]. | ||
=== Rückgabe === | === Rückgabe === | ||
| Zeile 267: | Zeile 267: | ||
lOk : Boolean; | lOk : Boolean; | ||
begin | begin | ||
// Benutzer und Rechte neu lesen, nicht aus dem alten Token | // Benutzer und Rechte neu lesen, nicht aus dem alten Token übernehmen | ||
cSql := 'SELECT ab_nr, ab_login, ab_mandant FROM APP_BENUTZER' + | cSql := 'SELECT ab_nr, ab_login, ab_mandant FROM APP_BENUTZER' + | ||
' WHERE ab_login = ' + DB_SQLVal(oReader.Subject()) + | ' WHERE ab_login = ' + DB_SQLVal(oReader.Subject()) + | ||
| Zeile 327: | Zeile 327: | ||
== Fehlerfälle == | == Fehlerfälle == | ||
Nur die Fälle der JWT-Anmeldung. Alle Fehlerantworten haben das Format aus [[OBS/Kostenpflichtige Module/ | Nur die Fälle der JWT-Anmeldung. Alle Fehlerantworten haben das Format aus [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]. Reagieren Sie auf <code>code</code>, nicht auf <code>message</code>. | ||
{| class="wikitable" | {| class="wikitable" | ||
| Zeile 359: | Zeile 359: | ||
|} | |} | ||
Die Gründe der Abweisungen stehen im Protokoll; die <code>traceId</code> der Antwort führt zur passenden Zeile. Siehe [[OBS/Kostenpflichtige Module/ | Die Gründe der Abweisungen stehen im Protokoll; die <code>traceId</code> der Antwort führt zur passenden Zeile. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]. | ||
== Siehe auch == | == Siehe auch == | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin|Zugangscode und Zertifikats-Pin]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]] | ||
Aktuelle Version vom 17. November 2026, 07:23 Uhr
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:
- 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. - Aufrufen: Jeder weitere Aufruf trägt das Access-Token im Header
Authorization: Bearer …. - Erneuern: Läuft das Access-Token ab, legt der Client das Refresh-Token am JWT-Endpunkt vor und erhält ein neues Paar.
- Abmelden: Ein
DELETEmit 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_EXPIREDund 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:
- Erneuern Sie nur einmal gleichzeitig. Weitere Anfragen, die in 401
AUTH_EXPIREDlaufen, warten auf das Ergebnis und verwenden dann das neue Access-Token. - Antwortet das Erneuern mit 401, legen Sie die Anmeldemaske vor.
- 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);
Authenticateläuft bei der Anmeldung. Der Körper der Anfrage steht im Reader.Refreshlä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_undstatusgehen nicht an den Client. Felder namenstoken,accessToken,refreshToken,expiresInundserverTimesetzt der Server selbst. - Die Claims
sid,ridundtoken_usesetzt 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
statusfü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
Refreshsie nicht neu schreibt. Eigene Claims und_OBS_JWT_REFRESH_IDmüssen dagegen neu geschrieben werden. Ohne_OBS_JWT_REFRESH_IDenthält die Antwort kein neues Refresh-Token.
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.