OBS/Kostenpflichtige Module/REST-Server/Zugänge: Unterschied zwischen den Versionen
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt] |
Prüfungen beim Speichern ergänzt: API-Key muss eindeutig sein, Lebenszeit mindestens 1 Minute [Volltext ersetzt] |
||
| Zeile 75: | Zeile 75: | ||
|} | |} | ||
Beim Speichern prüft OBS, ob '''Name''' und '''API-Key''' gefüllt sind, | Beim Speichern prüft OBS, ob '''Name''' und '''API-Key''' gefüllt sind und ob der '''API-Key''' keinem anderen Zugang gehört, auch nicht als vorheriger Key nach einem Schlüsseltausch. Mit '''JWT-Authentifizierung''' müssen zusätzlich '''Endpunkt''' und '''Secret-Key''' gefüllt sein, und '''Lebenszeit (Min)''' muss mindestens ''1'' betragen. | ||
=== API-Key und Zugang ohne Key === | === API-Key und Zugang ohne Key === | ||
Version vom 17. November 2026, 07:36 Uhr
Zugänge
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. Sie erreichen die Zugänge über Stammdaten → Z Weitere Stammdaten → REST-Server → Zugänge.
Liste
Die Liste zeigt alle Zugänge mit Name und Host. Aktive Zugänge erscheinen fett.
Dieselbe Liste öffnet sich auch zur Auswahl, wenn Sie in der Berechtigungsliste eines Endpunkts Einfg drücken, siehe Endpunkte. Sie zeigt dann zusätzlich die Spalte M für markierte Zugänge.
Tasten und Schaltflächen
| Taste | Funktion |
|---|---|
| Einfg | Legt einen neuen Zugang an. |
| ↩ Enter | Öffnet den markierten Zugang in der Eingabemaske. |
| F4 | Wählt die Sortierung. |
| F6 | Schaltfläche F6 QR: öffnet den Dialog Zugangscode für OBS-Smart-App, siehe Zugangscode. |
| F7 | Schaltfläche F7 JWT: öffnet das Anmeldeskript des Zugangs im Skript-Editor, siehe JWT-Authentifizierung. |
| F8 | Schaltfläche F8 Stat: zeigt die Statistik der Anfragen dieses Zugangs. |
Nur bei der Auswahl aus der Berechtigungsliste eines Endpunkts:
| Taste | Funktion |
|---|---|
| F5 | Markiert den Zugang oder hebt die Markierung auf. |
| F2 | Ordnet die markierten Zugänge dem Endpunkt zu. Ist nichts markiert, den Zugang unter dem Cursor. Die Liste schließt sich danach. |
Zugangscode
F6 ö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 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.
Eingabemaske
↩ Enter öffnet die Eingabemaske REST-Zugang. Ein neuer Zugang ist vorbelegt mit Aktiv 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. |
| 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 und API-Key gefüllt sind und ob der API-Key keinem anderen Zugang gehört, auch nicht als vorheriger Key nach einem Schlüsseltausch. Mit JWT-Authentifizierung müssen zusätzlich Endpunkt und Secret-Key gefüllt sein, und Lebenszeit (Min) muss mindestens 1 betragen.
API-Key und Zugang ohne Key
Der Client sendet den API-Key bei jeder Anfrage im Header apikey:
apikey: abcdef-ghij-klmn-opqr-stuvwx
Ein unbekannter Key ergibt 401 API_KEY_INVALID. Vergeben Sie jeden Key nur einmal. Alle Geräte mit demselben Key teilen sich einen Zähler der Anfragegrenze, siehe Server-Profile.
Fehlt der Header, verwendet der Server den Zugang mit dem API-Key *. Damit lassen sich bewusst öffentliche Endpunkte ohne Schlüssel anbieten. Gibt es keinen solchen Zugang, folgt 401 API_KEY_INVALID.
* 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.
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:
- Preflight: Der Browser fragt mit
OPTIONSvorab. 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. - Eigentliche Anfrage: Der Server prüft die Herkunft gegen die Liste dieses Zugangs. Passt sie nicht, antwortet er mit 403
FORBIDDEN_ROLEund 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-Headersanfragt. Eigene Header wieIdempotency-Key,If-Matchoder die Header des fortsetzbaren Uploads sind damit ohne Einstellung nutzbar. Fragt der Browser keine an, nennt der ServerContent-Type, apikey, Authorization, Accept. - Lesbare Antwort-Header:
Access-Control-Expose-HeadersnenntX-Trace-Id,ETag,LocationundRetry-Aftersowie die Header, die die Antwort sonst trägt.
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.
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 Berechtigung. Welche Anmeldedaten gelten, entscheidet das Anmeldeskript, das Sie mit F7 in der Liste 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.
Abweisungen im Überblick
| Ursache | Antwort an den Client |
|---|---|
API-Key unbekannt 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.