Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Zugänge: Unterschied zwischen den Versionen

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt]
MINERVA-Rademacker (Diskussion | Beiträge)
Weiterleitung auf Pflege#Zugang, Inhalt in die Seite Pflege übernommen [Volltext ersetzt]
Markierung: Neue Weiterleitung
 
(Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt)
Zeile 1: Zeile 1:
{{Vorlage:Kostenpflichtige Module}}
#WEITERLEITUNG [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Zugang]]
{{Seitentyp|Maske}}
= 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 [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte#Zugriffskontrolle|Endpunkte]]. Sie zeigt dann zusätzlich die Spalte '''M''' für markierte Zugänge.
 
== Tasten und Schaltflächen ==
{| class="wikitable"
! Taste !! Funktion
|-
| {{Einfg}} || Legt einen neuen Zugang an.
|-
| {{Return}} || Ö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|Zugangscode]].
|-
| {{F7}} || Schaltfläche '''F7 JWT''': öffnet das Anmeldeskript des Zugangs im Skript-Editor, siehe [[#JWT-Authentifizierung|JWT-Authentifizierung]].
|-
| {{F8}} || Schaltfläche '''F8 Stat''': zeigt die Statistik der Anfragen dieses Zugangs.
|}
 
Nur bei der Auswahl aus der Berechtigungsliste eines Endpunkts:
 
{| class="wikitable"
! 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 [[OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin|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:
 
<syntaxhighlight lang="text">
Vorheriger API-Key benutzt von <IP-Adresse> (gültig bis …)
</syntaxhighlight>
 
So sehen Sie, welche Geräte den neuen Code noch nicht haben.
 
== Eingabemaske ==
{{Return}} öffnet die Eingabemaske '''REST-Zugang'''. Ein neuer Zugang ist vorbelegt mit '''Aktiv''' und dem '''Endpunkt''' ''oauth''.
 
{| class="wikitable"
! 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|Host-Beschränkung]].
|-
| '''API-Key''' || Schlüssel, den der Client im Header <code>apikey</code> 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 <code>;</code> getrennt, siehe [[#CORS|CORS]].
|-
| '''mTLS-Subject''' || Optional. Bestandteile, die im Subject des Client-Zertifikats stehen müssen, siehe [[#mTLS-Subject|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, mit '''JWT-Authentifizierung''' zusätzlich '''Endpunkt''', '''Secret-Key''' und '''Lebenszeit (Min)'''.
 
=== API-Key und Zugang ohne Key ===
Der Client sendet den API-Key bei jeder Anfrage im Header <code>apikey</code>:
 
<syntaxhighlight lang="text">
apikey: abcdef-ghij-klmn-opqr-stuvwx
</syntaxhighlight>
 
Ein unbekannter Key ergibt '''401''' <code>API_KEY_INVALID</code>. Vergeben Sie jeden Key nur einmal. Alle Geräte mit demselben Key teilen sich einen Zähler der Anfragegrenze, siehe [[OBS/Kostenpflichtige Module/REST-Server/Server-Profile#Registerkarte: 2 Rate-Limits|Server-Profile]].
 
Fehlt der Header, verwendet der Server den Zugang mit dem API-Key <code>*</code>. Damit lassen sich bewusst öffentliche Endpunkte ohne Schlüssel anbieten. Gibt es keinen solchen Zugang, folgt '''401''' <code>API_KEY_INVALID</code>.
 
{{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 <code>*</code> wirkt auf die Preflight-Antworten aller Zugänge, und ein Download über die Adresszeile des Browsers sendet ohnehin kein <code>Origin</code>. Siehe auch [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|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 <code>X-Forwarded-For</code> wird für die Host-Beschränkung nicht ausgewertet, weil jeder Client ihn selbst setzen kann. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche#Betrieb hinter einem Reverse-Proxy|Betrieb und Fehlersuche]].}}
 
=== CORS ===
Ruft eine Browser-Anwendung den REST-Server auf, sendet der Browser den Header <code>Origin</code>. Diese Herkunft muss im Feld '''CORS-Origin''' des Zugangs stehen, z.B.:
 
<syntaxhighlight lang="text">
https://app.example.com;https://test.example.com;https://localhost:8080
</syntaxhighlight>
 
Verglichen wird jeder Eintrag vollständig mit Schema, Host und Port, ohne Rücksicht auf Groß- und Kleinschreibung. Tragen Sie die Adressen ohne <code>/</code> am Ende ein.
 
Ablauf:
# '''Preflight:''' Der Browser fragt mit <code>OPTIONS</code> 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.
# '''Eigentliche Anfrage:''' Der Server prüft die Herkunft gegen die Liste '''dieses''' Zugangs. Passt sie nicht, antwortet er mit '''403''' <code>FORBIDDEN_ROLE</code> 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 <code>*</code>, antwortet jeder Preflight mit <code>Access-Control-Allow-Origin: *</code>. Die eigentlichen Anfragen der übrigen Zugänge prüft der Server trotzdem gegen deren eigene Liste.
 
Die CORS-Header im Einzelnen:
* '''Methoden:''' <code>GET, POST, PUT, DELETE, PATCH</code>, fest vorgegeben.
* '''Anfrage-Header:''' Der Preflight erlaubt die Header, die der Browser in <code>Access-Control-Request-Headers</code> anfragt. Eigene Header wie <code>Idempotency-Key</code>, <code>If-Match</code> oder die Header des fortsetzbaren Uploads sind damit ohne Einstellung nutzbar. Fragt der Browser keine an, nennt der Server <code>Content-Type, apikey, Authorization, Accept</code>.
* '''Lesbare Antwort-Header:''' <code>Access-Control-Expose-Headers</code> nennt <code>X-Trace-Id</code>, <code>ETag</code>, <code>Location</code> und <code>Retry-After</code> 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 (<code>apikey</code>, <code>Authorization</code>) und nicht in Cookies. Eine fremde Seite kann also keine automatisch mitgesendete Berechtigung ausnutzen.}}
 
Was das Feld bewirkt:
 
{| class="wikitable"
! '''CORS-Origin''' !! Wirkung
|-
| leer || Kein Browser-Zugriff: Jede Anfrage mit <code>Origin</code> 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.
|-
| <code>*</code> || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antworten aller anderen Zugänge. Nur gezielt einsetzen.
|}
 
Für Clients ohne <code>Origin</code>-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 Berechtigung. Welche Anmeldedaten gelten, entscheidet das Anmeldeskript, das Sie mit {{F7}} in der Liste bearbeiten. Ablauf, Skript, Sitzungen und Fehlerfälle beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|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:
 
<syntaxhighlight lang="text">
/C=DE/O=Beispiel GmbH/CN=client-prod.example.com
/C=DE/O=Beispiel GmbH/CN=client-test.example.com
</syntaxhighlight>
 
Mit <code>CN=client-prod.example.com</code> im Feld nimmt der Server nur das erste Zertifikat an. Das zweite weist er mit '''401''' <code>CLIENT_CERT_INVALID</code> ab. <code>CN=client1</code> passt nicht auf <code>CN=client10</code>. Mehrere Bedingungen kombinieren Sie z.B. so: <code>O=Beispiel GmbH;CN=client-prod.example.com</code>.
 
{{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 ===
{| class="wikitable"
! Ursache !! Antwort an den Client
|-
| API-Key unbekannt oder kein Zugang mit <code>*</code> || '''401''' <code>API_KEY_INVALID</code>
|-
| Zugang inaktiv, falscher Host oder <code>Origin</code> nicht erlaubt || '''403''' <code>FORBIDDEN_ROLE</code>, Meldung „Zugriff verweigert“
|-
| Client-Zertifikat passt nicht zu '''mTLS-Subject''' || '''401''' <code>CLIENT_CERT_INVALID</code>
|-
| JWT: kein Token gesendet || '''401''' <code>AUTH_REQUIRED</code>
|-
| JWT: Anmeldung abgelehnt oder falscher Token-Typ || '''401''' <code>AUTH_FAILED</code>
|-
| JWT: Token abgelaufen oder Sitzung gesperrt || '''401''' <code>AUTH_EXPIRED</code>
|}
 
Den genauen Grund einer Abweisung nennt das Protokoll. Alle Fehlercodes und die empfohlene Reaktion des Clients beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]].
 
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/REST-Server/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin|Zugangscode und Zertifikats-Pin]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]

Aktuelle Version vom 17. November 2026, 11:53 Uhr