Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Pflege

Aus OBS Wiki
Version vom 17. November 2026, 11:49 Uhr von MINERVA-Rademacker (Diskussion | Beiträge) (Neue Seite: Pflege mit gekoppelten Listen für Server-Profile, Bindungen, Zugänge und Endpunkte; fasst die bisherigen Masken-Seiten zusammen)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)

Pflege

Die gesamte Einrichtung des REST-Servers erledigen Sie in einem Fenster: Server-Profile, ihre Bindungen, die Zugänge und die Endpunkte stehen nebeneinander und zeigen immer die Daten des markierten Profils. Einen Endpunkt für einen Zugang freischalten oder einen Zugangscode ausgeben ist damit eine Sache von einer Taste. Sie erreichen die Pflege über Stammdaten → Z Weitere Stammdaten → REST-Server.

Liste

Der Menüpunkt öffnet vier Listen, die als Einheit zusammenarbeiten:

Lage Liste Inhalt
links oben REST-Server Profile alle Server-Profile
links in der Mitte Bindungen die Bindungen des markierten Profils
links unten REST-Server Zugänge die Zugänge des markierten Profils
rechts, volle Höhe REST-Server Endpunkte die Endpunkte des markierten Profils

Aktive Einträge erscheinen in allen vier Listen fett.

Kopplung der Listen

  • Wechseln Sie in der Liste der Profile den Satz, zeigen die drei anderen Listen sofort Bindungen, Zugänge und Endpunkte dieses Profils.
  • Wechseln Sie in der Liste der Zugänge den Satz, zeigt die Spalte Zugriff der Endpunkte, welche Endpunkte dieser Zugang nutzen darf, siehe Zugriffskontrolle.
  • Ohne Profil, z.B. bei leerer Liste der Profile, bleiben die anderen Listen leer, und Einfg legt dort nichts an.

Wechsel zwischen den Listen

Sie wechseln per Mausklick oder mit der Tastatur:

Taste Liste
Strg+1 Profile
Strg+2 Bindungen
Strg+3 Zugänge
Strg+4 Endpunkte

Fensterlage

Die vier Listen bewegen sich gemeinsam. Verschieben Sie eine Liste, wandern die anderen mit. Ziehen Sie an der Kante zwischen zwei Listen, nimmt die Nachbarliste den Unterschied auf. Die rechte Liste der Endpunkte ist immer so hoch wie die drei linken Listen zusammen. OBS merkt sich die Lage beim Schließen und stellt sie beim nächsten Öffnen wieder her. Esc in einer der vier Listen schließt alle vier.

Spalten

Liste Spalten
Profile Name, Nr, Modus (TLS, mTLS oder kein SSL), Bindung (Adresse und Port der aktiven Standard-Bindung), Zert. bis (Ablauf des Zertifikats), Pin (1 bei eigenem Zertifikat mit Pin)
Bindungen Host, Port, Std (1 bei der Standard-Bindung)
Zugänge Name, Host, Endpunkte (Zahl der freigeschalteten Endpunkte), JWT (1 bei JWT-Anmeldung), CORS
Endpunkte Pfad (Pfad-Template), Zugriff (X, wenn der markierte Zugang den Endpunkt nutzen darf), Upload (1 bei Datei-Upload), M (markiert)

Tasten und Schaltflächen

In allen vier Listen gilt:

Taste Funktion
Einfg Legt einen neuen Eintrag an. Bindungen, Zugänge und Endpunkte erhalten das markierte Profil.
 ↩ Enter Öffnet den markierten Eintrag in der Eingabemaske.
Entf Löscht den markierten Eintrag. Ein Profil, an dem noch Bindungen, Zugänge oder Endpunkte hängen, löscht OBS nicht und nennt deren Anzahl.
F4 Wählt die Sortierung.

Dazu je Liste:

Liste Taste Funktion
Profile F8 Schaltfläche F8 Stat: zeigt die Statistik der Anfragen an dieses Profil.
Profile F10 Schaltfläche F10 Weitere: A Protokoll öffnet das Protokoll, B Statistik die Statistik aller Anfragen. Beides beschreibt Betrieb und Fehlersuche.
Zugänge F6 Schaltfläche F6 QR: öffnet den Dialog Zugangscode für OBS-Smart-App, siehe Zugangscode.
Zugänge F7 Schaltfläche F7 JWT: öffnet das Anmeldeskript des Zugangs im Skript-Editor, siehe JWT-Authentifizierung.
Zugänge F8 Schaltfläche F8 Stat: zeigt die Statistik der Anfragen dieses Zugangs.
Endpunkte F5 Markiert den Endpunkt oder hebt die Markierung auf.
Endpunkte F6 Schaltfläche F6 Zugriff: schaltet den Zugriff des markierten Zugangs auf diesen Endpunkt ein oder aus, siehe Zugriffskontrolle.
Endpunkte F7 Schaltfläche F7 Script: öffnet das Skript des Endpunkts im Skript-Editor. Wie Sie es schreiben, beschreibt Scripting.
Endpunkte F8 Schaltfläche F8 Stat: zeigt die Statistik der Anfragen an diesen Endpunkt.

Eingabemaske

 ↩ Enter öffnet die Eingabemaske der Liste, in der Sie stehen. Sichern Sie mit F2.

Server-Profil

Ein Server-Profil ist eine eigenständige Instanz des REST-Servers mit eigenem Modus, eigenen Zertifikaten, eigenen Grenzen und eigenen Bindungen. Sie betreiben beliebig viele Profile parallel und trennen so öffentliche Zugriffe sauber von internen. Typische Einsatzfälle für mehrere Profile:

  • Ein öffentliches Profil mit TLS auf Port 443 für externe Clients.
  • Ein mTLS-Profil auf einem internen Port für Systeme, die ein Client-Zertifikat vorlegen müssen.
  • Ein Debug-Profil mit Plain-HTTP, nur lokal erreichbar, für Tests.

Die Eingabemaske REST-Server hat fünf Registerkarten. Ein neues Profil ist vorbelegt mit Aktiv und den Standardwerten der Rate-Limits. mTLS-Modus aktiv ist aus.

Die Einstellungen liest der REST-Dienst beim Start. Eine Änderung wirkt erst nach einem Neustart des Dienstes. Ausnahme sind die Angaben zur automatischen Erneuerung auf den Registerkarten 4 und 5: Sie liest der Dienst bei jeder Prüfung neu.

Registerkarte: 1 Stammdaten

Feld Bedeutung
Nr Nummer des Profils von 1 bis 99. OBS schlägt die nächste freie Nummer vor. Nach dem Anlegen ist sie nicht mehr änderbar.
Name Eindeutiger Name. Er erscheint in Protokoll und Statistik.
zusätzliche Infos Freitext zur Dokumentation. Wird nicht ausgewertet.
kein SSL (Plain-HTTP - nur für Debug!) Das Profil spricht unverschlüsseltes HTTP. Die Zertifikatsfelder werden nicht ausgewertet. Nur für lokale Tests.
mTLS-Modus aktiv Jeder Client muss ein gültiges Client-Zertifikat vorlegen. Geprüft wird gegen das Root-Zertifikat (ca).
keine Kompression Antworten dieses Profils werden nicht mit gzip gepackt. Gepackte Anfragen nimmt der Server weiterhin an. Details: HTTP-Schnittstelle.
Aktiv Der REST-Dienst lädt das Profil beim Start. Inaktive Profile starten nicht.

Aus den Haken ergeben sich drei Betriebsarten:

Betriebsart Voraussetzungen Anwendung
Standard-TLS Zertifikat und Schlüssel Betrieb, auch intern, hinter einem Reverse-Proxy oder im VPN.
mTLS Zertifikat, Schlüssel und Root-Zertifikat, Haken mTLS-Modus aktiv Maschine-zu-Maschine-Verbindungen, bei denen jeder Client ein Zertifikat vorlegt.
Plain-HTTP Haken kein SSL (Plain-HTTP - nur für Debug!) Nur lokale Tests.

Falsch adressierte Verbindungen weist der Server vor jeder Verarbeitung ab:

  • http an ein TLS-Profil: Antwort 400 mit dem Klartext-Hinweis „Dieser Port erwartet eine TLS-Verbindung. Die Anfrage wurde im Klartext gesendet - bitte https verwenden.“
  • https an ein Plain-HTTP-Profil: Der Server trennt die Verbindung sofort. Kommt der TLS-Handshake erst nach dem Verbindungsaufbau, antwortet er mit 400. Im Protokoll steht die Meldung unter dem Host TLS:<Profil>.
HINWEIS: Fehlen bei Standard-TLS oder mTLS Zertifikat oder Schlüssel, startet nur dieses Profil nicht. Die übrigen Profile laufen. Im Protokoll steht „SSL/TLS-Konfiguration fehlt“. Bei aktiver Erneuerung trägt der Dienst beides selbst ein, mit Eigenes Zertifikat (Pin) stellt er sich selbst eines aus.

Registerkarte: 2 Rate-Limits

Feld Standard Bedeutung
Rate-Limit-Fenster 60 Länge des Zählfensters in Sekunden.
Erfolgsanfragen 120 Erlaubte Anfragen je Schlüssel und Fenster.
Fehlanfragen 10 Erlaubte Fehlanfragen je Schlüssel und Fenster.
Anfragen 600 Erlaubte Anfragen aller Clients des Profils je Fenster.
max. Verbindungen 200 Obergrenze gleichzeitig offener Verbindungen. Sie umfasst auch laufende Datei-Downloads. Darüber trennt der Server neue Verbindungen ohne HTTP-Antwort. Setzen Sie den Wert deutlich über den Normalbetrieb.
max. Anfragen 16 Obergrenze gleichzeitig verarbeiteter Anfragen. Darüber antwortet der Server mit 503 und Retry-After: 2. Der Client darf es also gleich erneut versuchen.

Die Spalte Standard nennt die Vorbelegung eines neuen Profils. Bei den vier Rate-Limit-Feldern gilt 0 als Standardwert, bei max. Verbindungen und max. Anfragen als unbegrenzt.

Jedes Profil führt eigene Zähler. Ein Profil unter Last bremst die anderen nicht aus.

Gezählt wird je Schlüssel. Schlüssel ist der Wert des Headers apikey, ohne Header die IP-Adresse. Alle Geräte mit demselben API-Key teilen sich also einen Zähler. Als Fehlanfrage zählt nur eine Anfrage, deren Zugang abgewiesen wird: API-Key unbekannt, Zugang inaktiv, Host-Beschränkung, Origin nicht erlaubt oder Client-Zertifikat passt nicht. Ein falsches Passwort bei der Anmeldung ist keine Fehlanfrage.

HINWEIS: Setzen Sie die Schwellen hoch genug für alle Geräte, die denselben API-Key verwenden. Hinter einem Reverse-Proxy teilen sich alle Anfragen ohne API-Key den Zähler der Proxy-Adresse, siehe Betrieb und Fehlersuche.

Was der Client bei einer Überschreitung erhält, beschreibt HTTP-Schnittstelle.

Registerkarte: 3 Zertifikate

Die Zertifikate stehen als Text im Profil. Tragen Sie sie im PEM-Format ein.

Feld Bedeutung
Zertifikat (cert) Server-Zertifikat als vollständige Kette: zuerst das Server-Zertifikat, danach die Zwischenzertifikate.
Schlüssel (key) Privater Schlüssel zum Server-Zertifikat.
Root-Zertifikat (ca) Zertifikat der Zertifizierungsstelle, gegen das die Client-Zertifikate geprüft werden. Nur bei mTLS, sonst leer.

Für TLS gilt:

  • TLS-Version: Der Server spricht ausschließlich TLS 1.2. Die Verschlüsselungsverfahren sind auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AES-GCM oder ChaCha20-Poly1305 beschränkt.
  • HSTS: Jede Antwort eines TLS-Profils trägt Strict-Transport-Security: max-age=31536000; includeSubDomains. Ein Browser spricht die Adresse damit ein Jahr lang nur über HTTPS an. Plain-HTTP-Profile setzen den Header nicht.
  • Zertifikatswechsel: Bei automatischer Erneuerung tauscht der Dienst das Zertifikat selbst und startet nur das betroffene Profil neu. Bei Pflege von Hand tragen Sie die neuen PEM-Inhalte ein und starten den REST-Dienst neu. Bis dahin läuft das alte Zertifikat weiter.

Registerkarte: 4 Zertifikaterneuerung

Der REST-Server kann sein Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Einrichtung und Ablauf beschreibt Zertifikatserneuerung.

Feld Bedeutung
Automatische Erneuerung deaktiviert: aus. Produktivbetrieb: Der Dienst beantragt und erneuert das Zertifikat selbst. Testbetrieb: nur für Testsysteme, siehe Testbetrieb.
Zertifikatsname (FQDN) Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist. Für die Erneuerung muss er von außen auf diesen Server zeigen. Beim eigenen Zertifikat mit Pin optional, siehe Eigenes Zertifikat und Pin.
Kontakt bei der CA Optional. E-Mail-Adresse, an die die Zertifizierungsstelle Warnungen schickt, wenn ein Zertifikat abzulaufen droht.
Zertifikat gültig bis Ablaufdatum des aktiven Zertifikats. Erneuert wird ab 30 Tagen Restlaufzeit.
Testzertifikat aus Staging Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt. Ihm vertraut kein Client.
Zustand idle: nichts zu tun. pending: Vorgang läuft. error: letzter Versuch fehlgeschlagen.
Letzte Meldung Ergebnis des letzten Vorgangs. Im Störungsfall das erste Feld, in das Sie sehen.
Gesperrt bis Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht.
Letzter Selbsttest am Zeitpunkt der letzten Prüfung über das Testsystem der Zertifizierungsstelle. Sie läuft wöchentlich und prüft, ob der Server von außen erreichbar ist.
Selbsttest bestanden Ergebnis dieser Prüfung.
Eigenes Zertifikat (Pin) Der Dienst stellt für dieses Profil ein eigenes Zertifikat aus und berechnet den Pin. Für interne Netze ohne eigene Domain, siehe Eigenes Zertifikat und Pin.
Zertifikats-Pin Pin des Schlüssels, mit dem das Profil TLS spricht, in der Form sha256/…. Der Dienst berechnet ihn. Nur Anzeige.

Die Felder von Zertifikat gültig bis bis Selbsttest bestanden sowie Zertifikats-Pin füllt der Dienst selbst.

Registerkarte: 5 DNS-Prüfung

Feld Bedeutung
Prüfart http-01 (Port 80) oder dns-01 (DNS-Eintrag), siehe Welche Prüfart?
DNS-Anbieter Nur dns-01: acme-dns, Hetzner, Cloudflare oder IONOS.
Adresse (acme-dns) Nur acme-dns: Adresse der Instanz. Sie beginnt mit https://.
Benutzer (acme-dns) Nur acme-dns: Benutzer des Kontos. Bleiben Benutzer, Schlüssel und Name leer, legt der Dienst das Konto selbst an.
Schlüssel / API-Token acme-dns: Passwort des Kontos. Hetzner und Cloudflare: API-Token. IONOS: API-Schlüssel in der Form Präfix.Secret.
Name des TXT-Eintrags Leer: _acme-challenge.<Zertifikatsname>. Bei CNAME-Delegation das Ziel des CNAME, bei acme-dns die fulldomain des Kontos.
HINWEIS: Die Zugangsdaten stehen im Klartext im Server-Profil. Verwenden Sie Token, die nur die nötige Zone ändern dürfen.

Eigenes Zertifikat und Pin

In internen Netzen ohne eigene Domain ist keine Zertifizierungsstelle erreichbar. Für diesen Fall stellt der Dienst selbst ein Zertifikat aus, und die App vertraut über einen Pin genau diesem Schlüssel.

  1. Setzen Sie auf der Registerkarte 4 Zertifikaterneuerung den Haken Eigenes Zertifikat (Pin).
  2. Tragen Sie unter Zertifikatsname (FQDN) die Adresse ein, unter der das Gerät den Server erreicht, wenn es eine gibt. Auch eine IP-Adresse ist zulässig.
  3. Lassen Sie Zertifikat (cert) und Schlüssel (key) leer und starten Sie den REST-Dienst neu.

Fehlt Zertifikat oder Schlüssel, stellt der Dienst beim Start ein Zertifikat aus: RSA 3072, gültig 3650 Tage. Er berechnet den Pin und zeigt ihn unter Zertifikats-Pin. Ein vollständig hinterlegtes Zertifikat ändert er nie. Den Pin gibt OBS im Zugangscode an die App weiter.

Den Namen im Zertifikat nimmt der Dienst in dieser Reihenfolge:

  1. Zertifikatsname (FQDN).
  2. Ist das Feld leer, die Adresse der aktiven Standard-Bindung, sofern dort eine bestimmte Adresse steht. 0.0.0.0, ::, 127.0.0.1 und localhost zählen nicht, unter ihnen erreicht kein Gerät den Server.
  3. Sonst trägt das Zertifikat nur den Namen OBS REST.

Mit Pin prüft die App weder Namen noch Ablaufdatum, nur den Schlüssel. Ein Zertifikat ohne passenden Namen ist für sie deshalb kein Problem. Beim Speichern eines Profils mit Pin ohne Zertifikatsname (FQDN) zeigt OBS einen Hinweis, auf welchen Namen das Zertifikat ausgestellt wird.

ACHTUNG: Ein neuer Schlüssel macht jeden bisher ausgegebenen Zugangscode mit Pin ungültig. Ändert sich der Pin, meldet der Dienst das im Protokoll. Für einen Wechsel ohne Ausfall geben Sie vorher Codes mit altem und neuem Pin aus. Im Feld Zertifikats-Pin des Zugangscode-Dialogs trennen Sie mehrere Pins durch Komma.

Eigenes Zertifikat (Pin) schließt sich aus mit Automatische Erneuerung und mit kein SSL (Plain-HTTP - nur für Debug!). Pin-Format, Prüfung durch die App und Schlüsselwechsel beschreibt Zugangscode und Zertifikats-Pin.

Prüfungen beim Speichern

Was Sie eintragen, prüft OBS immer, auch bei einem nicht aktiven Profil:

  • Nr und Name sind vergeben. Nr besteht nur aus Ziffern und liegt zwischen 1 und 99.
  • Nr und Name sind eindeutig.
  • Zertifikat (cert) und Schlüssel (key) liegen im PEM-Format vor. Bei kein SSL (Plain-HTTP - nur für Debug!) entfällt diese Prüfung.
  • Zertifikatsname (FQDN) ist ein Name mit Punkt, ohne Adresse, Port, Leerzeichen und Platzhalter *. Er beginnt und endet nicht mit Punkt oder Bindestrich.
  • Kontakt bei der CA ist eine E-Mail-Adresse.
  • Eigenes Zertifikat (Pin) ist weder mit der automatischen Erneuerung noch mit kein SSL (Plain-HTTP - nur für Debug!) kombiniert.
  • Adresse (acme-dns) beginnt mit https://. Name des TXT-Eintrags ist ein gültiger Name.

Nur bei einem aktiven Profil prüft OBS zusätzlich:

  • Ohne kein SSL (Plain-HTTP - nur für Debug!), ohne automatische Erneuerung und ohne Eigenes Zertifikat (Pin) sind Zertifikat und Schlüssel vorhanden.
  • Bei mTLS-Modus aktiv ist das Root-Zertifikat vorhanden.
  • Bei aktiver Erneuerung ist Zertifikatsname (FQDN) vergeben und kein SSL (Plain-HTTP - nur für Debug!) nicht gesetzt.
  • Bei der Prüfart dns-01 ist ein DNS-Anbieter gewählt. Bei acme-dns ist die Adresse eingetragen, und Benutzer, Schlüssel und Name sind entweder alle gefüllt oder alle leer. Bei den übrigen Anbietern ist Schlüssel / API-Token gefüllt.
  • Bei Testbetrieb fragt OBS vor dem Speichern nach, weil dem Testzertifikat kein Client vertraut.

Bindung

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Ein Profil kann mehrere Bindungen haben, z.B. um dieselbe TLS-Konfiguration auf zwei Ports anzubieten. Die Eingabemaske heißt REST-Bindung.

Feld Bedeutung
Host IP-Adresse, auf der der Server lauscht. 0.0.0.0 steht für alle IPv4-Adressen. Eine bestimmte Adresse bindet an genau diese Netzwerkkarte. Pflichtfeld.
Port TCP-Port. Pflichtfeld.
Server Das Server-Profil, zu dem die Bindung gehört. Vorbelegt mit dem markierten Profil.
Aktiv Der Dienst legt die Bindung beim Start an.
Standard Markiert die Standard-Bindung des Profils. Ihren Port übernimmt der Dialog Zugangscode für OBS-Smart-App, und ihre Adresse dient als Ersatz, wo kein Zertifikatsname (FQDN) eingetragen ist. Je Profil gibt es nur eine aktive Standard-Bindung. Setzen Sie den Haken bei einer zweiten, fragt OBS, ob der Standard auf diese Bindung wechseln soll. Mit Ja verliert die bisherige Standard-Bindung den Haken.

Bindungen liest der Dienst nur beim Start. Bis zum Neustart laufen die alten Bindungen weiter. Lässt sich das Profil auf einer Bindung nicht starten, z.B. weil der Port belegt ist, steht im Protokoll:

Fehler: Server [<Name>] konnte nicht gestartet werden (…)

Zugang

Ein Zugang ist der Kanal, über den eine App, eine Webseite oder ein Fremdsystem den REST-Server anspricht. Je Zugang legen Sie fest, wer ihn nutzen darf: per API-Key, Absenderadresse, Browser-Herkunft, Client-Zertifikat und auf Wunsch mit persönlicher Anmeldung per JWT. So erhält jede Anwendung genau den Zugriff, den sie braucht.

Die Eingabemaske heißt REST-Zugang. Ein neuer Zugang ist vorbelegt mit Aktiv, dem markierten Profil unter Server und dem Endpunkt oauth.

Feld Bedeutung
Name Name des Zugangs. Er erscheint in Protokoll und Statistik. Pflichtfeld.
Host Optional. IP-Adresse oder Hostname, von dem die Anfragen kommen müssen, siehe Host-Beschränkung.
API-Key Schlüssel, den der Client im Header apikey sendet. Die Schaltfläche ... erzeugt einen neuen Key aus 28 Zeichen. Ein vorhandener Key wird erst nach Rückfrage überschrieben. Pflichtfeld.
CORS-Origin Herkunftsadressen, von denen Browser den Zugang nutzen dürfen, mehrere durch ; getrennt, siehe CORS.
mTLS-Subject Optional. Bestandteile, die im Subject des Client-Zertifikats stehen müssen, siehe mTLS-Subject.
Server Das Server-Profil des Zugangs. Der API-Key gilt nur auf diesem Profil. Pflichtfeld.
Aktiv Nur aktive Zugänge werden angenommen. Anfragen an einen inaktiven Zugang weist der Server mit 403 ab.
JWT-Authentifizierung Haken: Jeder Aufruf dieses Zugangs verlangt ein Token aus der Anmeldung. Die drei folgenden Felder sind nur mit Haken bearbeitbar.
Endpunkt Pfad des JWT-Endpunkts, über den Anmelden, Erneuern und Abmelden laufen. Pflichtfeld bei JWT-Authentifizierung.
Secret-Key Geheimer Schlüssel für die Signatur der Token. Die Schaltfläche ... erzeugt einen neuen Schlüssel aus 50 Zeichen. Ein neuer Secret-Key macht alle ausgegebenen Token ungültig. Pflichtfeld bei JWT-Authentifizierung.
Lebenszeit (Min) Laufzeit des Access-Tokens in Minuten. Pflichtfeld bei JWT-Authentifizierung.

Beim Speichern prüft OBS, ob Name, API-Key und Server gefüllt sind und ob der API-Key keinem anderen Zugang gehört, auch nicht als vorheriger Key nach einem Schlüsseltausch und auch nicht auf einem anderen Profil. Mit JWT-Authentifizierung müssen zusätzlich Endpunkt und Secret-Key gefüllt sein, und Lebenszeit (Min) muss mindestens 1 betragen.

Wechseln Sie das Server-Profil eines Zugangs, der Endpunkte freigeschaltet hat, fragt OBS nach: Die Freischaltungen gehören zu Endpunkten des bisherigen Profils und werden beim Wechsel entfernt. Schalten Sie die Endpunkte danach auf dem neuen Profil frei.

Endpunkt

Ein Endpunkt stellt eine Adresse bereit, über die der REST-Server eine Funktion anbietet. Hinter jedem Endpunkt steht ein OBS-Skript oder ein WebHook. So veröffentlichen Sie genau die Daten und Vorgänge, die eine Anwendung braucht, und vergeben die Rechte je Adresse.

Die Eingabemaske heißt REST-Endpunkt. Ein neuer Endpunkt ist vorbelegt mit Aktiv und dem markierten Profil unter Server.

Feld Bedeutung
Pfad-Template Vollständiger Pfad nach Host und Port, mit Platzhaltern, z.B. /orders/{uid}/modules/{code}. Maßgeblich für die Zuordnung der Anfragen, siehe Routing über Pfad-Templates. Pflichtfeld.
Server Server-Profil, auf dem der Endpunkt erreichbar ist. Auf anderen Profilen antwortet der Server für diesen Pfad mit 404. Pflichtfeld.
zusätzliche Infos Freitext zur Dokumentation. Wird nicht ausgewertet.
Datei-Upload Der Endpunkt nimmt Dateien an. Ohne Haken weist der Server Uploads mit 415 ab, das Skript läuft dann nicht.
maximale Dateigröße (MB) Obergrenze für Uploads in MB. Leer oder 0 bedeutet 25 MB. Darüber antwortet der Server mit 413.
Aktiv Nur aktive Endpunkte sind erreichbar. Ein inaktiver Endpunkt antwortet mit 404.

Das Skript des Endpunkts bearbeiten Sie in der Liste mit F7.

Zugriffskontrolle

Ein Zugang darf einen Endpunkt nur nutzen, wenn er dafür freigeschaltet ist. Die Freischaltungen stehen in der Tabelle RESTSRV_ACCESS.

So schalten Sie Endpunkte für einen Zugang frei:

  1. Markieren Sie in der Liste der Zugänge den Zugang. Die Spalte Zugriff der Endpunkte zeigt mit X, welche Endpunkte er schon nutzen darf.
  2. Wechseln Sie mit Strg+4 in die Liste der Endpunkte.
  3. Drücken Sie F6 auf dem Endpunkt. Der Zugriff wird eingeschaltet, ein zweites F6 schaltet ihn wieder aus.
  4. Für mehrere Endpunkte auf einmal markieren Sie diese mit F5 und drücken dann F6. Alle markierten Endpunkte erhalten den Zustand, der dem Endpunkt unter dem Cursor fehlt.

Die Spalte Endpunkte der Zugänge zählt die Freischaltungen mit. Ein Zugang kann nur Endpunkte seines eigenen Profils nutzen. Der JWT-Endpunkt eines Zugangs braucht keine Freischaltung.

ACHTUNG: Ein Endpunkt ohne Freischaltung sieht fertig aus: Pfad, Skript und Server-Profil stimmen, der Aufruf scheitert trotzdem mit 403 FORBIDDEN_ROLE und der Meldung „Zugriff verweigert“. Im Protokoll steht „Keine Berechtigung für die Endpunkt-Nutzung“. Schalten Sie deshalb beim Anlegen immer auch den Zugriff frei, und prüfen Sie bei einem 403 zuerst die Spalte Zugriff.

Weil jede Pfad-Form ein eigener Endpunkt ist, vergeben Sie die Rechte je Pfad-Form. So erlauben Sie z.B. das Lesen von /orders/{uid}, aber nicht das Ändern über /orders/{uid}/modules/{code}.

Zugangscode

F6 in der Liste der Zugänge öffnet den Dialog Zugangscode für OBS-Smart-App. Er belegt Adresse, App-Kennung, API-Key und bei Bedarf den Zertifikats-Pin aus der Einrichtung des Zugangs und seines Profils vor und erzeugt daraus den Zugangscode, den die App als QR-Code einliest. Felder, Tasten, Format und Prüfregeln beschreibt Zugangscode und Zertifikats-Pin.

Schlüssel tauschen: F3 im Dialog erzeugt nach Rückfrage einen neuen API-Key und speichert ihn sofort am Zugang. Der bisherige Key gilt so viele Tage weiter, wie unter Alter Key noch Tage steht. Vorbelegt sind 14. Mit 0 gilt der alte Key sofort nicht mehr. Solange die Frist läuft, schreibt der Server bei jeder Nutzung des alten Keys eine Zeile ins Protokoll:

Vorheriger API-Key benutzt von <IP-Adresse> (gültig bis …)

So sehen Sie, welche Geräte den neuen Code noch nicht haben.

Absicherung eines Zugangs

API-Key und Zugang ohne Key

Der Client sendet den API-Key bei jeder Anfrage im Header apikey:

apikey: abcdef-ghij-klmn-opqr-stuvwx

Der Key gilt nur auf dem Server-Profil, das am Zugang unter Server eingetragen ist. Ein unbekannter Key oder ein Key, der zu einem anderen Profil gehört, ergibt 401 API_KEY_INVALID. Welcher der beiden Fälle vorliegt, nennt nur das Protokoll. Vergeben Sie jeden Key nur einmal. Alle Geräte mit demselben Key teilen sich einen Zähler der Anfragegrenze, siehe Registerkarte: 2 Rate-Limits.

Fehlt der Header, verwendet der Server den Zugang mit dem API-Key *. Damit lassen sich bewusst öffentliche Endpunkte ohne Schlüssel anbieten. Weil jeder Key nur einmal vergeben wird, gibt es diesen Zugang nur auf einem Profil. Gibt es keinen solchen Zugang auf dem angesprochenen Profil, folgt 401 API_KEY_INVALID.

ACHTUNG: Ein Zugang ohne Key kennt weder Mandant noch Benutzer. Nutzen Sie ihn nur für Inhalte, die für jeden bestimmt sind, z.B. ein Handbuch oder eine Test-App, nie für Kundenbelege. Beschränken Sie ihn nach Möglichkeit mit Host. Lassen Sie CORS-Origin dort leer: Ein * wirkt auf die Preflight-Antworten aller Zugänge, und ein Download über die Adresszeile des Browsers sendet ohnehin kein Origin. Siehe auch Datei-Download.

Host-Beschränkung

Steht im Feld Host ein Wert, nimmt der Server Anfragen dieses Zugangs nur an, wenn die IP-Adresse der Verbindung gleich diesem Wert ist oder der Hostname auf diese IP-Adresse auflöst. Das Ergebnis der Namensauflösung hält der Server 5 Minuten vor. Andere Absender erhalten 403.

HINWEIS: Hinter einem Reverse-Proxy ist die IP-Adresse der Verbindung immer die des Proxys. Der Header X-Forwarded-For wird für die Host-Beschränkung nicht ausgewertet, weil jeder Client ihn selbst setzen kann. Siehe Betrieb und Fehlersuche.

CORS

Ruft eine Browser-Anwendung den REST-Server auf, sendet der Browser den Header Origin. Diese Herkunft muss im Feld CORS-Origin des Zugangs stehen, z.B.:

https://app.example.com;https://test.example.com;https://localhost:8080

Verglichen wird jeder Eintrag vollständig mit Schema, Host und Port, ohne Rücksicht auf Groß- und Kleinschreibung. Tragen Sie die Adressen ohne / am Ende ein.

Ablauf:

  1. Preflight: Der Browser fragt mit OPTIONS vorab. Der Server antwortet immer mit 204, noch vor Anfragegrenze und Authentifizierung und ohne API-Key. CORS-Header setzt er nur, wenn die Herkunft bei irgendeinem aktiven Zugang eingetragen ist. Diese Liste aller Zugänge hält er 60 Sekunden vor. Der Browser darf die Antwort 600 Sekunden zwischenspeichern.
  2. Eigentliche Anfrage: Der Server prüft die Herkunft gegen die Liste dieses Zugangs. Passt sie nicht, antwortet er mit 403 FORBIDDEN_ROLE und der Meldung „Zugriff verweigert“. Den Grund „Origin … nicht erlaubt“ nennt nur das Protokoll.

Der Preflight kann nicht je Zugang prüfen, weil der Browser dabei keinen API-Key mitsendet. Durchgesetzt wird deshalb in Schritt 2. Steht bei einem Zugang *, antwortet jeder Preflight mit Access-Control-Allow-Origin: *. Die eigentlichen Anfragen der übrigen Zugänge prüft der Server trotzdem gegen deren eigene Liste.

Die CORS-Header im Einzelnen:

  • Methoden: GET, POST, PUT, DELETE, PATCH, fest vorgegeben.
  • Anfrage-Header: Der Preflight erlaubt die Header, die der Browser in Access-Control-Request-Headers anfragt. Eigene Header wie Idempotency-Key, If-Match oder die Header des fortsetzbaren Uploads sind damit ohne Einstellung nutzbar. Fragt der Browser keine an, nennt der Server Content-Type, apikey, Authorization, Accept.
  • Lesbare Antwort-Header: Access-Control-Expose-Headers nennt X-Trace-Id, ETag, Location und Retry-After sowie die Header, die die Antwort sonst trägt.
HINWEIS: Die Header-Liste ist keine Schutzgrenze, das ist die Herkunft. Die Zugangsdaten stehen in Headern (apikey, Authorization) und nicht in Cookies. Eine fremde Seite kann also keine automatisch mitgesendete Berechtigung ausnutzen.

Was das Feld bewirkt:

CORS-Origin Wirkung
leer Kein Browser-Zugriff: Jede Anfrage mit Origin wird mit 403 abgewiesen. Richtig für Zugänge, die nur Apps oder Server nutzen.
bestimmte Adressen Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen.
* Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antworten aller anderen Zugänge. Nur gezielt einsetzen.

Für Clients ohne Origin-Header, also Apps, Server oder curl, spielt das Feld keine Rolle.

HINWEIS: Bei einer Browser-Anwendung liegt der API-Key zwangsläufig im JavaScript und ist damit öffentlich. Die Herkunftsliste verhindert, dass eine fremde Seite ihn im Browser nutzt. Sie ersetzt aber keine Zugriffskontrolle: Außerhalb des Browsers lässt sich CORS mit dem Key umgehen.

JWT-Authentifizierung

Mit dem Haken JWT-Authentifizierung meldet sich jeder Benutzer einer App einzeln an und erhält ein zeitlich begrenztes Token. Anmelden, Erneuern und Abmelden laufen über den Pfad im Feld Endpunkt. Dieser Pfad braucht keinen Eintrag unter den Endpunkten und keine Freischaltung. Welche Anmeldedaten gelten, entscheidet das Anmeldeskript, das Sie mit F7 in der Liste der Zugänge bearbeiten. Ablauf, Skript, Sitzungen und Fehlerfälle beschreibt Anmeldung mit JWT.

mTLS-Subject

Steht im Feld mTLS-Subject ein Wert, prüft der Server zusätzlich, ob das Subject des Client-Zertifikats die angegebenen Bestandteile enthält. Jeder Bestandteil wird vollständig verglichen, ohne Rücksicht auf Groß- und Kleinschreibung. Mehrere Bestandteile trennen Sie durch Komma oder Semikolon. Sie müssen alle vorkommen.

Beispiele für das Subject zweier Client-Zertifikate:

/C=DE/O=Beispiel GmbH/CN=client-prod.example.com
/C=DE/O=Beispiel GmbH/CN=client-test.example.com

Mit CN=client-prod.example.com im Feld nimmt der Server nur das erste Zertifikat an. Das zweite weist er mit 401 CLIENT_CERT_INVALID ab. CN=client1 passt nicht auf CN=client10. Mehrere Bedingungen kombinieren Sie z.B. so: O=Beispiel GmbH;CN=client-prod.example.com.

HINWEIS: Das Feld wirkt nur auf Server-Profilen mit mTLS-Modus aktiv. Ohne geprüftes Client-Zertifikat weist der Server jede Anfrage eines Zugangs mit mTLS-Subject ab.

Abweisungen im Überblick

Ursache Antwort an den Client
API-Key unbekannt, Zugang gehört zu einem anderen Server-Profil oder kein Zugang mit * 401 API_KEY_INVALID
Zugang inaktiv, falscher Host oder Origin nicht erlaubt 403 FORBIDDEN_ROLE, Meldung „Zugriff verweigert“
Client-Zertifikat passt nicht zu mTLS-Subject 401 CLIENT_CERT_INVALID
JWT: kein Token gesendet 401 AUTH_REQUIRED
JWT: Anmeldung abgelehnt oder falscher Token-Typ 401 AUTH_FAILED
JWT: Token abgelaufen oder Sitzung gesperrt 401 AUTH_EXPIRED

Den genauen Grund einer Abweisung nennt das Protokoll. Alle Fehlercodes und die empfohlene Reaktion des Clients beschreibt HTTP-Schnittstelle.

Routing über Pfad-Templates

Der Server ordnet jede Anfrage über das Pfad-Template einem Endpunkt zu:

  • Statische Segmente müssen übereinstimmen. Groß- und Kleinschreibung spielt keine Rolle.
  • Platzhalter in geschweiften Klammern, z.B. {uid}, passen auf jeden Wert. Der Wert steht dem Skript als Pfad-Parameter zur Verfügung.
  • Die Zahl der Segmente muss gleich sein. /orders passt nicht auf /orders/{uid}.
Template Passt auf Pfad-Parameter
/orders /orders –
/orders/{uid} /orders/4711 uid = 4711
/orders/{uid}/modules/{code} /orders/4711/modules/A1 uid = 4711, code = A1
/kalender/v1 /kalender/v1 –

Passen mehrere Templates, gewinnt das spezifischste, also das mit den meisten statischen Segmenten. So schlägt /orders/summary das Template /orders/{uid}, während /orders/4711 auf /orders/{uid} passt. Haben zwei Templates gleich viele statische Segmente, ist nicht festgelegt, welches gewinnt. Vermeiden Sie solche Überschneidungen.

Passt kein Template, antwortet der Server mit 404 NOT_FOUND. Weitere Regeln, z.B. zu Schrägstrichen und Query-Parametern, beschreibt HTTP-Schnittstelle.

Pfad-Parameter im Skript

Das Skript liest die Werte der Platzhalter über oReader.Path:

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
    cUid := oReader.Path('uid');   // aus /orders/{uid}
end;

Der Name des Parameters ist geschützt: Query-Parameter oder Header können ihn nicht überschreiben. Der Wert kommt aber aus der Adresse, die der Client sendet. Prüfen Sie ihn im Skript wie jede andere Eingabe. Details: Scripting.

URL-Struktur

https://<Host>[:<Port>]<Pfad-Template>

Beispiele:

HTTP-Methode

Der Server ruft im Skript die Methode auf, die zum HTTP-Verb passt: Get, Post, Put, Patch oder Delete. Fehlt die Methode im Skript, antwortet er mit 405 und nennt im Header Allow die vorhandenen.

Ein Template entspricht damit einem Skript. Unterschiedliche Pfad-Formen wie /orders und /orders/{uid} sind eigene Endpunkte mit eigenem Skript und eigener Freischaltung.

Schreibende Aufrufe (POST, PUT, PATCH, DELETE) schützt der Server selbst gegen doppelte Ausführung. Der Client sendet dafür den Header Idempotency-Key, am Endpunkt ist nichts einzustellen. Details: HTTP-Schnittstelle.

Versionierung

Die Version eines Endpunkts nehmen Sie als statisches Segment ins Template auf, z.B. /orders/v1 oder /v1/orders/{uid}. Eine Änderung ohne Bruch für bestehende Clients:

  1. Lassen Sie den bestehenden Endpunkt unverändert.
  2. Legen Sie einen neuen Endpunkt mit neuem Versions-Segment an.
  3. Schalten Sie den Zugriff für die Clients frei, die umstellen.
  4. Deaktivieren Sie den alten Endpunkt, wenn alle Clients umgestellt sind.

Dateien

  • Upload: Mit Datei-Upload nimmt der Endpunkt Dateien an, bis zur maximalen Dateigröße (MB). Übertragungsarten, Header und Statuscodes beschreibt Datei-Upload.
  • Download: Jeder Endpunkt kann statt JSON eine Datei liefern, ohne Einstellung am Endpunkt. Das Skript erzeugt die Datei-Antwort, siehe Datei-Download.

Caching

Der Server hält die Endpunkte eines Server-Profils samt Skript 60 Sekunden im Speicher. Neue oder geänderte Endpunkte, Templates und Skripte wirken deshalb spätestens nach 60 Sekunden. Nach einem Neustart des REST-Dienstes wirken sie sofort.

WebHooks

Ein WebHook ist ein Endpunkt für einen einmaligen Rückruf. Typischer Einsatz: OBS stößt einen Vorgang bei einem Fremdsystem an, z.B. einem Bezahldienst oder Versanddienstleister, und gibt ihm eine Rückruf-Adresse mit, die nur einmal gilt. Die Adresse lässt sich danach nicht erneut oder von anderen benutzen.

Ablauf:

  1. OBS legt einen Eintrag in der Tabelle REMOTE_HOOK_URL an und dazu einen Endpunkt, der auf diesen Eintrag verweist. Ein Skript hat dieser Endpunkt nicht.
  2. Die Adresse dieses Endpunkts erhält das Fremdsystem als Rückruf-Adresse.
  3. Das Fremdsystem ruft die Adresse auf. Der Server speichert den empfangenen Inhalt in REMOTE_HOOK_URL.hu_response, antwortet mit {"status": "ok"} und löscht den Endpunkt.
  4. Der weiterverarbeitende OBS-Vorgang liest die Rückmeldung aus hu_response.

Für den Aufruf gilt:

  • Wie bei jedem Endpunkt prüft der Server API-Key und Freischaltung des Zugangs.
  • Ein Idempotency-Key ist nicht nötig.
  • Ein zweiter Aufruf derselben Adresse erhält sofort 404. Das ist gewollt: Ein WebHook ist keine dauerhafte Schnittstelle. Für eine dauerhafte Rückmelde-Adresse legen Sie einen normalen Endpunkt mit Skript an.
  • Fehlt der Eintrag in REMOTE_HOOK_URL, antwortet der Server mit 500.

Siehe auch