OBS/Kostenpflichtige Module/REST-Server/Beispiele/Daten-Abruf mit JWT-Anmeldung: Unterschied zwischen den Versionen
Keine Bearbeitungszusammenfassung |
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt] |
||
| (10 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 1: | Zeile 1: | ||
{{Kostenpflichtige Module}} | {{Vorlage:Kostenpflichtige Module}} | ||
{{Seitentyp|Referenz}} | |||
= Daten-Abruf mit JWT-Anmeldung = | |||
In diesem Beispiel zeigt eine Webseite Steuerungs-Variablen aus OBS an – live, ohne Export und ohne eigene Datenbank. Der Zugang verlangt eine JWT-Anmeldung: Jeder Benutzer meldet sich zuerst an und ruft die Daten dann mit seinem Token ab. | |||
== Einrichtung in OBS == | |||
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443 | |||
==Einrichtung in OBS== | |||
* '''Server-Profil:''' | |||
* '''Zugang:''' ''Web-Dashboard'' | * '''Zugang:''' ''Web-Dashboard'' | ||
** API-Key: | ** '''API-Key:''' vom System erzeugt | ||
** JWT | ** Haken '''JWT-Authentifizierung''' gesetzt, '''Endpunkt''' <code>/oauth</code>, '''Secret-Key''' zufällig, '''Lebenszeit (Min)''' ''60'' | ||
** CORS- | ** '''CORS-Origin:''' <code><nowiki>https://dashboard.example.com</nowiki></code> | ||
* '''Endpunkt:''' ''steuerung/v1'' | * '''Endpunkt:''' '''Pfad-Template''' <code>/steuerung/v1</code>, '''Server''' ''Public-API'' | ||
* '''Berechtigung:''' Zugang ''Web-Dashboard'' | * '''Berechtigung:''' Zugang ''Web-Dashboard'' für den Endpunkt <code>/steuerung/v1</code> freigeschaltet | ||
Felder und Bedienung: [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] und [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]. | |||
== Anmeldeskript des Zugangs == | |||
Das Anmeldeskript öffnen Sie in der Zugänge-Liste mit {{F7}}. Es prüft Benutzername und Passwort und schreibt bei Erfolg die Angaben für das Token. Tabelle, Felder und <code>HashPasswort</code> stehen für Ihre eigene Prüfung. Den vollständigen Ablauf mit Erneuern und Abmelden beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]. | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="delphi"> | ||
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var | var cUser: string; | ||
cPass: string; | |||
cPass : string; | cSql : string; | ||
cSql | qUser: TxFQuery; | ||
qUser : TxFQuery; | lOk : Boolean; | ||
begin | begin | ||
cUser := ''; | |||
cPass := ''; | |||
oReader.Str('username', cUser); | |||
oReader.Str('password', cPass); | |||
cSql := 'SELECT u_nr, u_name FROM BENUTZER' + | |||
' WHERE u_login = ' + DB_SqlVal(cUser, 'C') + | |||
' AND u_passwort_hash = ' + DB_SqlVal(HashPasswort(cPass), 'C') + | |||
' AND u_aktiv = ' + DB_SqlVal('1', 'C'); | |||
// 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; | |||
oWriter.Int('status' , 1); | |||
oWriter.Str('_OBS_JWT_ID' , qUser.A2C('u_nr')); | |||
oWriter.Str('_OBS_JWT_SUBJECT' , qUser.A2C('u_name')); | |||
oWriter.Str('_OBS_JWT_AUDIENCE', 'dashboard'); | |||
end; | end; | ||
end; | |||
DB_Close(qUser); | |||
if (not lOk) then begin | |||
oWriter.Int('status', 9); | |||
oWriter.Str('error' , 'Benutzer oder Passwort ist falsch'); | |||
end; | end; | ||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Das Skript schreibt kein <code>_OBS_JWT_REFRESH_ID</code>. Die Antwort enthält deshalb kein Refresh-Token, und der Benutzer meldet sich nach Ablauf der '''Lebenszeit (Min)''' neu an. | |||
== Endpunkt-Skript == | |||
Das Skript des Endpunkts <code>/steuerung/v1</code> liefert eine Liste von Steuerungs-Werten. Es beantwortet nur Token mit der Audience ''dashboard''. | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="delphi"> | ||
procedure _AddVar( | // Schreibt eine Variable als Listeneintrag an die aktuelle Stelle des Writers | ||
var | procedure _AddVar(oWriter: TxRestWriter; const cVar: string); | ||
var cTitel : string; | |||
cData : string; | cData : string; | ||
cEinh : string; | cEinh : string; | ||
| Zeile 72: | Zeile 72: | ||
begin | begin | ||
if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin | if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin | ||
oWriter.ObjBegin(''); | |||
oWriter.Str('variable', cVar); | |||
oWriter.Str('titel' , cTitel); | |||
oWriter.Str('wert' , cData); | |||
oWriter.Str('einheit' , cEinh); | |||
oWriter.ObjEnd; | |||
end; | end; | ||
end; | end; | ||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | |||
begin | begin | ||
// | // Nur Token, die für das Dashboard ausgestellt wurden | ||
if ( | if (oReader.Param('_OBS_JWT_AUDIENCE') <> 'dashboard') then begin | ||
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Token nicht für diese Anwendung ausgestellt'); | |||
exit; | exit; | ||
end; | end; | ||
// Die Antwort ist eine Liste: RootArr vor dem ersten Eintrag, ohne ArrEnd | |||
oWriter.RootArr(); | |||
_AddVar(oWriter, 'WERT_1'); | |||
_AddVar(oWriter, 'WERT_2'); | |||
_AddVar(oWriter, 'WERT_3'); | |||
_AddVar(oWriter, 'WERT_4'); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Werte, deren Name mit <code>_OBS_</code> beginnt, kann der Client weder über Header noch über Query-Parameter setzen. Die Prüfung der Audience ist deshalb verlässlich. | |||
== Aufruf aus JavaScript == | |||
Die Webseite meldet sich an und liest dann die Daten. Die Anmeldung ist ein <code>POST</code> an den JWT-Endpunkt und braucht keinen <code>Idempotency-Key</code>; der Datenabruf ist ein <code>GET</code>. | |||
<syntaxhighlight lang="javascript" | <syntaxhighlight lang="javascript"> | ||
const API_BASE = 'https:// | const API_BASE = 'https://obs.example.com'; | ||
const API_KEY = ' | const API_KEY = 'abcdef-ghij-klmn-opqr-stuvwx'; | ||
// Wirft bei einer Fehlerantwort den Code aus dem error-Objekt | |||
async function pruefeAntwort(res) { | |||
if (res.ok) { | |||
return res.json(); | |||
} | |||
let code = 'HTTP_' + res.status; | |||
try { | |||
const fehler = await res.json(); | |||
code = fehler.error.code; | |||
} catch (e) { | |||
// Antwort ohne JSON-Körper | |||
} | |||
throw new Error(code + ' (X-Trace-Id ' + res.headers.get('X-Trace-Id') + ')'); | |||
} | |||
async function login(username, password) { | async function login(username, password) { | ||
const res = await fetch(`${API_BASE}/oauth | const res = await fetch(`${API_BASE}/oauth`, { | ||
method: 'POST', | method: 'POST', | ||
headers: { 'Content-Type': 'application/json', 'apikey': API_KEY }, | headers: { 'Content-Type': 'application/json', 'apikey': API_KEY }, | ||
body: JSON.stringify({ username, password }) | body: JSON.stringify({ username, password }) | ||
}); | }); | ||
const data = await pruefeAntwort(res); | |||
const data = await res | return data.accessToken; | ||
return data. | |||
} | } | ||
| Zeile 127: | Zeile 135: | ||
const res = await fetch(`${API_BASE}/steuerung/v1`, { | const res = await fetch(`${API_BASE}/steuerung/v1`, { | ||
method: 'GET', | method: 'GET', | ||
headers: { | headers: { 'apikey': API_KEY, 'Authorization': 'Bearer ' + token } | ||
}); | }); | ||
return pruefeAntwort(res); | |||
} | } | ||
async function zeigeTabelle() { | async function zeigeTabelle(username, password) { | ||
const token = await login( | const token = await login(username, password); | ||
const werte = await ladeSteuerung(token); | const werte = await ladeSteuerung(token); | ||
| Zeile 147: | Zeile 151: | ||
}); | }); | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Der Aufruf aus dem Browser gelingt nur, wenn die Adresse der Webseite im Feld '''CORS-Origin''' des Zugangs steht. Sonst antwortet der Server mit 403. | |||
== Test mit curl == | |||
Anmelden: | |||
<syntaxhighlight lang="bash"> | |||
curl -X POST \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Content-Type: application/json" \ | |||
-d '{"username":"mitarbeiter","password":"geheim"}' \ | |||
https://obs.example.com/oauth | |||
</syntaxhighlight> | |||
Antwort: | Antwort: | ||
<syntaxhighlight lang="json"> | |||
{ | |||
"token": "eyJhbGciOiJIUzI1NiIs...", | |||
"accessToken": "eyJhbGciOiJIUzI1NiIs...", | |||
"expiresIn": 3600, | |||
"serverTime": "2026-11-17T09:12:33+01:00" | |||
} | |||
</syntaxhighlight> | |||
Daten abrufen: | Daten abrufen: | ||
<syntaxhighlight lang="bash"> | |||
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ | |||
https://obs.example.com/steuerung/v1 | |||
</syntaxhighlight> | |||
Ein falsches Passwort beantwortet der Server mit 401 <code>AUTH_FAILED</code> und dem Text aus dem Anmeldeskript. Ein Abruf ohne Token ergibt 401 <code>AUTH_REQUIRED</code>, ein abgelaufenes Token 401 <code>AUTH_EXPIRED</code>. Alle Codes: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]. | |||
==Was zeigt das Beispiel?== | == Was zeigt das Beispiel? == | ||
* Zweistufiger Zugriff: API-Key für den Zugang, JWT für den einzelnen Benutzer. | |||
* Ein Anmeldeskript je Zugang, das die Benutzer gegen eigene Daten prüft. | |||
* Trennung von Anwendungen über die Audience des Tokens. | |||
* Eine Liste als Antwort über <code>oWriter.RootArr</code> und einen Helfer, der den Writer als Parameter bekommt. | |||
* Fehlerantworten über <code>oWriter.Error</code> im einheitlichen Fehlerformat. | |||
* Browser-Zugriff über ein erlaubtes '''CORS-Origin'''. | |||
* Anmeldung ohne Refresh-Token: der einfachste Fall. | |||
* | == Siehe auch == | ||
* | * [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]] | ||
* | * [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | ||
* | * [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] | ||
* [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]] | |||
Aktuelle Version vom 17. November 2026, 07:23 Uhr
Daten-Abruf mit JWT-Anmeldung
In diesem Beispiel zeigt eine Webseite Steuerungs-Variablen aus OBS an – live, ohne Export und ohne eigene Datenbank. Der Zugang verlangt eine JWT-Anmeldung: Jeder Benutzer meldet sich zuerst an und ruft die Daten dann mit seinem Token ab.
Einrichtung in OBS
- Server-Profil: TLS-Profil Public-API mit einer Bindung auf Port 443
- Zugang: Web-Dashboard
- API-Key: vom System erzeugt
- Haken JWT-Authentifizierung gesetzt, Endpunkt
/oauth, Secret-Key zufällig, Lebenszeit (Min) 60 - CORS-Origin:
https://dashboard.example.com
- Endpunkt: Pfad-Template
/steuerung/v1, Server Public-API - Berechtigung: Zugang Web-Dashboard für den Endpunkt
/steuerung/v1freigeschaltet
Felder und Bedienung: Zugänge und Endpunkte.
Anmeldeskript des Zugangs
Das Anmeldeskript öffnen Sie in der Zugänge-Liste mit F7. Es prüft Benutzername und Passwort und schreibt bei Erfolg die Angaben für das Token. Tabelle, Felder und HashPasswort stehen für Ihre eigene Prüfung. Den vollständigen Ablauf mit Erneuern und Abmelden beschreibt Anmeldung mit JWT.
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 u_nr, u_name FROM BENUTZER' +
' WHERE u_login = ' + DB_SqlVal(cUser, 'C') +
' AND u_passwort_hash = ' + DB_SqlVal(HashPasswort(cPass), 'C') +
' AND u_aktiv = ' + DB_SqlVal('1', 'C');
// 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;
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , qUser.A2C('u_nr'));
oWriter.Str('_OBS_JWT_SUBJECT' , qUser.A2C('u_name'));
oWriter.Str('_OBS_JWT_AUDIENCE', 'dashboard');
end;
end;
DB_Close(qUser);
if (not lOk) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Benutzer oder Passwort ist falsch');
end;
end;
Das Skript schreibt kein _OBS_JWT_REFRESH_ID. Die Antwort enthält deshalb kein Refresh-Token, und der Benutzer meldet sich nach Ablauf der Lebenszeit (Min) neu an.
Endpunkt-Skript
Das Skript des Endpunkts /steuerung/v1 liefert eine Liste von Steuerungs-Werten. Es beantwortet nur Token mit der Audience dashboard.
// Schreibt eine Variable als Listeneintrag an die aktuelle Stelle des Writers
procedure _AddVar(oWriter: TxRestWriter; const cVar: string);
var cTitel : string;
cData : string;
cEinh : string;
lString: Boolean;
lAlign : Boolean;
begin
if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin
oWriter.ObjBegin('');
oWriter.Str('variable', cVar);
oWriter.Str('titel' , cTitel);
oWriter.Str('wert' , cData);
oWriter.Str('einheit' , cEinh);
oWriter.ObjEnd;
end;
end;
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// Nur Token, die für das Dashboard ausgestellt wurden
if (oReader.Param('_OBS_JWT_AUDIENCE') <> 'dashboard') then begin
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Token nicht für diese Anwendung ausgestellt');
exit;
end;
// Die Antwort ist eine Liste: RootArr vor dem ersten Eintrag, ohne ArrEnd
oWriter.RootArr();
_AddVar(oWriter, 'WERT_1');
_AddVar(oWriter, 'WERT_2');
_AddVar(oWriter, 'WERT_3');
_AddVar(oWriter, 'WERT_4');
end;
Werte, deren Name mit _OBS_ beginnt, kann der Client weder über Header noch über Query-Parameter setzen. Die Prüfung der Audience ist deshalb verlässlich.
Aufruf aus JavaScript
Die Webseite meldet sich an und liest dann die Daten. Die Anmeldung ist ein POST an den JWT-Endpunkt und braucht keinen Idempotency-Key; der Datenabruf ist ein GET.
const API_BASE = 'https://obs.example.com';
const API_KEY = 'abcdef-ghij-klmn-opqr-stuvwx';
// Wirft bei einer Fehlerantwort den Code aus dem error-Objekt
async function pruefeAntwort(res) {
if (res.ok) {
return res.json();
}
let code = 'HTTP_' + res.status;
try {
const fehler = await res.json();
code = fehler.error.code;
} catch (e) {
// Antwort ohne JSON-Körper
}
throw new Error(code + ' (X-Trace-Id ' + res.headers.get('X-Trace-Id') + ')');
}
async function login(username, password) {
const res = await fetch(`${API_BASE}/oauth`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'apikey': API_KEY },
body: JSON.stringify({ username, password })
});
const data = await pruefeAntwort(res);
return data.accessToken;
}
async function ladeSteuerung(token) {
const res = await fetch(`${API_BASE}/steuerung/v1`, {
method: 'GET',
headers: { 'apikey': API_KEY, 'Authorization': 'Bearer ' + token }
});
return pruefeAntwort(res);
}
async function zeigeTabelle(username, password) {
const token = await login(username, password);
const werte = await ladeSteuerung(token);
const tbl = document.getElementById('steuerung');
werte.forEach(w => {
const tr = document.createElement('tr');
tr.innerHTML = `<td>${w.titel}</td><td>${w.wert} ${w.einheit}</td>`;
tbl.appendChild(tr);
});
}
Der Aufruf aus dem Browser gelingt nur, wenn die Adresse der Webseite im Feld CORS-Origin des Zugangs steht. Sonst antwortet der Server mit 403.
Test mit curl
Anmelden:
curl -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Content-Type: application/json" \
-d '{"username":"mitarbeiter","password":"geheim"}' \
https://obs.example.com/oauth
Antwort:
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 3600,
"serverTime": "2026-11-17T09:12:33+01:00"
}
Daten abrufen:
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
https://obs.example.com/steuerung/v1
Ein falsches Passwort beantwortet der Server mit 401 AUTH_FAILED und dem Text aus dem Anmeldeskript. Ein Abruf ohne Token ergibt 401 AUTH_REQUIRED, ein abgelaufenes Token 401 AUTH_EXPIRED. Alle Codes: HTTP-Schnittstelle.
Was zeigt das Beispiel?
- Zweistufiger Zugriff: API-Key für den Zugang, JWT für den einzelnen Benutzer.
- Ein Anmeldeskript je Zugang, das die Benutzer gegen eigene Daten prüft.
- Trennung von Anwendungen über die Audience des Tokens.
- Eine Liste als Antwort über
oWriter.RootArrund einen Helfer, der den Writer als Parameter bekommt. - Fehlerantworten über
oWriter.Errorim einheitlichen Fehlerformat. - Browser-Zugriff über ein erlaubtes CORS-Origin.
- Anmeldung ohne Refresh-Token: der einfachste Fall.