Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Beispiele/Daten-Abruf mit JWT-Anmeldung: Unterschied zwischen den Versionen

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Die Seite wurde neu angelegt: „{{Kostenpflichtige Module}} Bei diesem Beispiel werden Daten aus dem Steuerungs-Modul abgerufen und in einer Tabelle auf einer Webseite angezeigt. =Endpunkt-Script= procedure _AddVar(oArr: TJSONArray; cVar: string); var oWert : TJSONObject; cTitel : string; cData : string; cEinheit: string; lString : Boolean; lAlign : Boolean; begin if (ST_Variable(oDB, cVar, cTitel, cData, cEinheit, lString, lAlign)) then begin…“
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
(13 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Referenz}}
= Daten-Abruf mit JWT-Anmeldung =


Bei diesem Beispiel werden Daten aus dem Steuerungs-Modul abgerufen und in einer Tabelle auf einer Webseite angezeigt.
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.


=Endpunkt-Script=
== 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''' <code>/oauth</code>, '''Secret-Key''' zufällig, '''Lebenszeit (Min)''' ''60''
** '''CORS-Origin:''' <code><nowiki>https://dashboard.example.com</nowiki></code>
* '''Endpunkt:''' '''Pfad-Template''' <code>/steuerung/v1</code>, '''Server''' ''Public-API''
* '''Berechtigung:''' Zugang ''Web-Dashboard'' für den Endpunkt <code>/steuerung/v1</code> freigeschaltet


procedure _AddVar(oArr: TJSONArray; cVar: string);
Felder und Bedienung: [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] und [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]].
var oWert  : TJSONObject;
    cTitel  : string;
    cData  : string;
    cEinheit: string;
    lString : Boolean;
    lAlign  : Boolean;
begin
    if (ST_Variable(oDB, cVar, cTitel, cData, cEinheit, lString, lAlign)) then begin
        oWert := TJSONObject.Create();
       
        oWert.AddPair('Variable', cVar);
        oWert.AddPair('Titel'  , cTitel);
        oWert.AddPair('Wert'    , cData);
        oWert.AddPair('Einheit' , cEinheit);
        oArr.Add(oWert);
    end;
end;
//------------------------------------------------------------------------------
function Get(oParams: TStrings): string;
var oArr: TJSONArray;
begin
    result := '';
    oArr := TJSONArray.Create();
    _AddVar(oArr, 'WERT_1');
    _AddVar(oArr, 'WERT_2');
    _AddVar(oArr, 'WERT_3');
    _AddVar(oArr, 'WERT_4');
    result := oArr.ToJSON();
end;


=PHP-Script=
== 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]].


  <?php
<syntaxhighlight lang="delphi">
    $data = [];             // hier könnten Parameter übergeben werden
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
    $curl = curl_init();
var cUser: string;
    $url  = '''[HOSTADRESSE]'':''[PORT]''/''[ENDPUNKT]''/v1';
    cPass: string;
     $url  = sprintf("%s?%s", $url, http_build_query($data));
    cSql : string;
    qUser: TxFQuery;
    $headers = [
    lOk : Boolean;
        'apikey: ''[API-KEY]'''
begin
    ];
    cUser := '';
   
    cPass := '';
    curl_setopt($curl, CURLOPT_URL, $url);
    oReader.Str('username', cUser);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    oReader.Str('password', cPass);
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
 
    curl_setopt($curl, CURLOPT_TIMEOUT, 2);
    cSql := 'SELECT u_nr, u_name FROM BENUTZER' +
            ' WHERE u_login = '         + DB_SqlVal(cUser, 'C') +
    if( $result = curl_exec($curl)) {
            '   AND u_passwort_hash = ' + DB_SqlVal(HashPasswort(cPass), 'C') +
        $data = json_decode($result);
            '   AND u_aktiv = '         + DB_SqlVal('1', 'C');
 
        echo "&lt;table&gt;&lt;tr&gt;&lt;td width='200'&gt;&lt;/td&gt;&lt;td width='150'&gt;&lt;/td&gt;&lt;/tr&gt;";
    // DB_SOpen meldet nur, dass die Abfrage lief. Gefunden ist erst bei not EoF.
   
    lOk := false;
        foreach ($data as $value) {
    if (DB_SOpen(oDB, cSql, qUser)) then begin
            echo "&lt;tr&gt;&lt;td&gt;".$value-&gt;Titel."&lt;/td&gt;&lt;td&gt;".$value-&gt;Wert." ".$value-&gt;Einheit."&lt;/td&gt;&lt;/tr&gt;";
        if (not qUser.EoF) then begin
        }
            lOk := true;
            oWriter.Int('status'           , 1);
        echo "&lt;/table&gt;";
            oWriter.Str('_OBS_JWT_ID'     , qUser.A2C('u_nr'));
     }
            oWriter.Str('_OBS_JWT_SUBJECT' , qUser.A2C('u_name'));
            oWriter.Str('_OBS_JWT_AUDIENCE', 'dashboard');
     curl_close($curl);
        end;
?>
    end;
    DB_Close(qUser);
 
    if (not lOk) then begin
        oWriter.Int('status', 9);
        oWriter.Str('error' , 'Benutzer oder Passwort ist falsch');
    end;
end;
</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="delphi">
// 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;
</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">
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);
    });
}
</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:
 
<syntaxhighlight lang="json">
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600,
  "serverTime": "2026-11-17T09:12:33+01:00"
}
</syntaxhighlight>
 
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? ==
* 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/v1 freigeschaltet

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.RootArr und einen Helfer, der den Writer als Parameter bekommt.
  • Fehlerantworten über oWriter.Error im einheitlichen Fehlerformat.
  • Browser-Zugriff über ein erlaubtes CORS-Origin.
  • Anmeldung ohne Refresh-Token: der einfachste Fall.

Siehe auch