Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Zugangscode fuer die OBS-Smart-App mit F6 ergaenzt [Volltext ersetzt]
MINERVA-Rademacker (Diskussion | Beiträge)
Typ Maske, H1 Zugänge; Felder/Tasten aus Maske; JWT und Zugangscode gekürzt mit Links; CORS (403 FORBIDDEN_ROLE, Preflight 204) und 401-Codes korrigiert [Volltext ersetzt]
Zeile 1: Zeile 1:
{{Vorlage:Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Maske}}
= Zugänge =


=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'''.


Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.
== Liste ==
Die Liste zeigt alle Zugänge mit '''Name''' und '''Host'''. Aktive Zugänge erscheinen fett.


==Aufruf==
Dieselbe Liste öffnet sich auch zur Auswahl, wenn Sie in der Berechtigungsliste eines Endpunkts {{Einfg}} drücken, siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte#Zugriffskontrolle|Endpunkte]]. Sie zeigt dann zusätzlich die Spalte '''M''' für markierte Zugänge.
 
'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''
 
==Felder==


== Tasten und Schaltflächen ==
{| class="wikitable"
{| class="wikitable"
! Feld          !! Beschreibung
! Taste !! Funktion
|-
| Name          || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv        || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key      || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host          || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
|-
| CORS-Origins  || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
| {{Einfg}} || Legt einen neuen Zugang an.
|-
|-
| mTLS-Subject  || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
| {{Return}} || Öffnet den markierten Zugang in der Eingabemaske.
|-
|-
| JWT          || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
| {{F4}} || Wählt die Sortierung.
|-
|-
| JWT-Endpunkt  || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
| {{F6}} || Schaltfläche '''F6 QR''': öffnet den Dialog '''Zugangscode für OBS-Smart-App''', siehe [[#Zugangscode|Zugangscode]].
|-
|-
| JWT-Key      || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
| {{F7}} || Schaltfläche '''F7 JWT''': öffnet das Anmeldeskript des Zugangs im Skript-Editor, siehe [[#JWT-Authentifizierung|JWT-Authentifizierung]].
|-
|-
| JWT-Exp      || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
| {{F8}} || Schaltfläche '''F8 Stat''': zeigt die Statistik der Anfragen dieses Zugangs.
|}
|}


==API-Key==
Nur bei der Auswahl aus der Berechtigungsliste eines Endpunkts:
 
Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:
 
apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12
 
Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.
 
{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}
 
{{Achtung|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Ein Wildcard-Zugang eignet
sich deshalb für Artefakte, die für jeden bestimmt sind (Test-APK, Handbuch),
'''nicht''' für Kundenbelege. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].}}
 
{{Hinweis|Bei einem Wildcard-Zugang sollte ''CORS-Origin'' '''leer''' bleiben.
Ein ''*'' dort wirkt auf die Preflight-Antwort '''aller''' Zugänge (siehe unten);
ein Download über die Adresszeile des Browsers sendet ohnehin kein ''Origin'',
CORS greift dort also gar nicht.}}
 
==Host-Beschränkung==
 
Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.
 
{{Hinweis|Hinter einem Reverse-Proxy ist die Remote-IP immer die des Proxys. Die Host-Beschränkung kann dort keine einzelnen Konsumenten unterscheiden. Der Header ''X-Forwarded-For'' wird dafür bewusst nicht ausgewertet, weil jeder Client ihn selbst setzen kann.}}
 
==CORS==
 
Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.
 
Format der Liste:
 
https://app.firma.de;https://test.firma.de;https://localhost:8080
 
Ablauf:
 
# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.
 
Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.
 
Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).
 
Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.
 
{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}
 
===Was „leer" bedeutet===
 
{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}
 
Daraus ergeben sich drei sinnvolle Einstellungen:


{| class="wikitable"
{| class="wikitable"
! Feld !! Wirkung
! Taste !! Funktion
|-
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
| {{F5}} || Markiert den Zugang oder hebt die Markierung auf.
|-
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
| {{F2}} || Ordnet die markierten Zugänge dem Endpunkt zu. Ist nichts markiert, den Zugang unter dem Cursor. Die Liste schließt sich danach.
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}
|}


Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
=== Zugangscode ===
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
{{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/RESTServer/Zugangscode und Zertifikats-Pin|Zugangscode und Zertifikats-Pin]].
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.


==JWT-Authentifizierung==
'''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:


Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).
<syntaxhighlight lang="text">
Vorheriger API-Key benutzt von <IP-Adresse> (gueltig bis …)
</syntaxhighlight>


'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
So sehen Sie, welche Geräte den neuen Code noch nicht haben.
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.


Unterschieden wird nach Verb und Token-Art:
== Eingabemaske ==
{{Return}} öffnet die Eingabemaske '''REST-Zugang'''. Ein neuer Zugang ist vorbelegt mit '''Aktiv''' und dem '''Endpunkt''' ''oauth''.


{| class="wikitable"
{| class="wikitable"
! Aufruf !! Ablauf
! 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]].
|-
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
| '''Aktiv''' || Nur aktive Zugänge werden angenommen. Anfragen an einen inaktiven Zugang weist der Server mit '''403''' ab.
|-
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
| '''JWT-Authentifizierung''' || Haken: Jeder Aufruf dieses Zugangs verlangt ein Token aus der Anmeldung. Die drei folgenden Felder sind nur mit Haken bearbeitbar.
|-
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
| '''Endpunkt''' || Pfad des JWT-Endpunkts, über den Anmelden, Erneuern und Abmelden laufen. Pflichtfeld bei '''JWT-Authentifizierung'''.
|-
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
| '''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'''.
|}
|}


{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Beim Speichern prüft OBS, ob '''Name''' und '''API-Key''' gefüllt sind, mit '''JWT-Authentifizierung''' zusätzlich '''Endpunkt''', '''Secret-Key''' und '''Lebenszeit (Min)'''.
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}


===Phase 1: Token-Bezug===
=== API-Key und Zugang ohne Key ===
Der Client sendet den API-Key bei jeder Anfrage im Header <code>apikey</code>:


Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:
<syntaxhighlight lang="text">
apikey: abcdef-ghij-klmn-opqr-stuvwx
</syntaxhighlight>


POST https://api.meinserver.de/oauth/
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/RESTServer/Server-Profile#Registerkarte: 2 Rate-Limits|Server-Profile]].
Header: apikey: [API-KEY]
Body:  {"username":"...", "password":"..."}


Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Prozedur ''Authenticate'' bereitstellen, die über den Writer schreibt:
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>.


* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
{{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/RESTServer/Datei-Download|Datei-Download]].}}
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_&lt;name&gt;'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)


{{Achtung|Die Lebensdauer eines Refresh-Tokens ist nach oben auf '''372 Tage'''
=== Host-Beschränkung ===
begrenzt. Ein mit ''_OBS_JWT_REFRESH_EXP'' länger ausgestelltes Token wird bei der
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'''.
Vorlage '''nicht mehr verifiziert''' und mit 401 abgewiesen - der Fehler fällt
also erst Monate später auf, beim ersten Erneuerungsversuch.}}


Die Signatur lautet ''procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);'' - Details unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:
{{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/RESTServer/Betrieb und Fehlersuche#Betrieb hinter einem Reverse-Proxy|Betrieb und Fehlersuche]].}}


{"token":        "eyJhbGciOi...",
=== CORS ===
  "accessToken":  "eyJhbGciOi...",
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.:
  "expiresIn":    28800,
  "serverTime":  "2026-06-29T15:30:12+02:00"}


Zum Aufbau der Antwort:
<syntaxhighlight lang="text">
https://app.example.com;https://test.example.com;https://localhost:8080
</syntaxhighlight>


* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
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.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.


Beispiel mit Zusatzfeldern aus dem Skript:
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.
{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
# '''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.
  "token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
  "expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}
 
Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.
 
Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''', dem Code ''AUTH_FAILED'' und reicht den Text aus dem Feld
''error'' als ''error.message'' an den Client durch - der Konsument kann ihn also
direkt anzeigen. Die Formulierung liegt damit beim Skript.
 
{{Hinweis|''AUTH_FAILED'' unterscheidet die '''abgelehnte Anmeldung''' vom
''AUTH_EXPIRED'', das ein abgelaufenes oder gesperrtes Token liefert. Ein Client
sollte auf den Code reagieren und nicht auf den Text: Bei ''AUTH_FAILED'' gehört
die Anmeldemaske noch einmal vorgelegt, bei ''AUTH_EXPIRED'' erst ein Refresh
versucht.}}
 
{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}
 
===Phase 2: Token-Verwendung===
 
Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:
 
GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
        Authorization: Bearer eyJhbGciOi...
 
Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.
 
Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.
 
{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}
 
===Phase 3: Token erneuern (Refresh)===
 
Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:


POST https://api.meinserver.de/oauth/
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.
Header: apikey: [API-KEY]
        Authorization: Bearer eyJhbGciOi... (Refresh-Token)


Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.
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.


{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
{{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.}}
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}


Verhalten bei einem bereits benutzten Refresh-Token:
Was das Feld bewirkt:


{| class="wikitable"
{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
! '''CORS-Origin''' !! Wirkung
|-
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
| 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.
|-
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
| 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.
|}
|}


Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
Für Clients ohne <code>Origin</code>-Header, also Apps, Server oder curl, spielt das Feld keine Rolle.


===Phase 4: Abmelden (Logout)===
{{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.}}


Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
=== JWT-Authentifizierung ===
Access-Token im ''Authorization''-Header:
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/RESTServer/Anmeldung mit JWT|Anmeldung mit JWT]].


DELETE https://api.meinserver.de/oauth/
=== mTLS-Subject ===
Header: apikey: [API-KEY]
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.
        Authorization: Bearer eyJhbGciOi... (Access-Token)


HTTP/1.1 204 No Content
Beispiele für das Subject zweier Client-Zertifikate:


Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
<syntaxhighlight lang="text">
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
/C=DE/O=Beispiel GmbH/CN=client-prod.example.com
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
/C=DE/O=Beispiel GmbH/CN=client-test.example.com
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.
 
* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.
 
====Alle Geräte abmelden====
 
Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
''oWriter.JwtRevoke'', das jeder gewöhnliche Endpunkt aufrufen kann:
 
<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
    // 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
    oWriter.JwtRevoke('all');
    oWriter.Status(204);
    oWriter.NoBody();
end;
</syntaxhighlight>
</syntaxhighlight>


{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
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>.
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}
 
==Woher ein Anmelder seine Identität bekommt==


'''Diese Frage entscheidet das Skript des Zugangs, nicht der Server.''' Das
{{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.}}
Authentifizierungs-Skript liegt je Zugang in <code>ra_jwt_script</code> - und
damit gilt für jede Anwendung ihre eigene Regel.
 
Das ist keine Kleinigkeit, sondern der Punkt, an dem sich zwei Anwendungen
unterscheiden. Ein Beispiel aus dem Betrieb: Ein Zugang für eine
Techniker-Anwendung lehnt jeden Benutzer ohne Mitarbeiterzuordnung
(<code>BENUTZ.b_mitarbeiter</code>) ab - '''bewusst''', denn ein Techniker ohne
Zuordnung bekäme eine leere Auftragsliste und würde den Fehler bei sich suchen.
Für einen Kundenzugang wäre genau dieselbe Regel falsch: sie träfe '''jeden'''
Anmelder.
 
Wer einen zweiten Zugang für eine andere Anwendung anlegt, prüft deshalb als
Erstes: Woraus besteht die Identität dieser Anmelder, und welche Ablehnung ist
für sie richtig? Ein kopiertes Skript bringt die Regel der anderen Anwendung
mit, und sie fällt erst auf, wenn sich der erste echte Anmelder nicht anmelden
kann.
 
==Sitzungen (RESTSRV_TOKEN)==
 
Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt". Schickt ein Reverse-Proxy den Header
''X-Forwarded-For'' mit, steht dessen Wert zusätzlich in ''rt_ip_fwd''; ''rt_ip'' bleibt
die IP-Adresse der Verbindung.
 
* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.
 
==mTLS-Subject-Prüfung==
 
Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.
 
Beispiele für Subject-Strings im Cert (OneLine-DN):
 
/C=DE/O=Firma GmbH/CN=client-prod.firma.de
/C=DE/O=Firma GmbH/CN=client-test.firma.de
 
Mit '''CN=client-prod.firma.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Firma GmbH;CN=client-prod.firma.de''.
 
==Zugangscode für die App==
 
Ein Gerät mit einer OBS-Smart-App braucht drei Angaben: die Adresse des REST-Servers, den API-Key des Zugangs und - in internen Netzen - den Zertifikats-Pin. OBS fasst sie zu einem '''Zugangscode''' zusammen, den die App als QR-Code einliest.
 
Markieren Sie den Zugang in der Liste und drücken Sie {{F6}}. Der Dialog belegt alle Felder aus der vorhandenen Einrichtung vor; überschreiben können Sie jedes davon.


=== Abweisungen im Überblick ===
{| class="wikitable"
{| class="wikitable"
! Feld !! Woher der Vorschlag kommt
! Ursache !! Antwort an den Client
|-
| '''App''' || Erstes Segment des Endpunkt-Pfades, zum Beispiel ''service''. Sind dem Zugang Endpunkte mehrerer Apps zugeordnet, weist der Dialog darauf hin
|-
| '''Host (FQDN)''' || Zertifikatsname des Server-Profils. Hier gehört die Adresse hinein, unter der das '''Gerät''' den Server erreicht - nicht die, auf der der Dienst lauscht
|-
| '''Port''' || Standard-Bindung des Server-Profils, sonst die erste aktive
|-
| '''HTTPS''' || Aus dem Server-Profil
|-
| '''Anzeigename''' || Name des Zugangs. Er erscheint in der App als Bezeichnung der Verbindung
|-
|-
| '''API-Key''' || Der API-Key des Zugangs
| API-Key unbekannt oder kein Zugang mit <code>*</code> || '''401''' <code>API_KEY_INVALID</code>
|-
|-
| '''Zertifikats-Pin''' || Nur, wenn das Server-Profil einen führt, siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Eigenes Zertifikat und Pin|Eigenes Zertifikat und Pin]]
| Zugang inaktiv, falscher Host oder <code>Origin</code> nicht erlaubt || '''403''' <code>FORBIDDEN_ROLE</code>, Meldung „Zugriff verweigert“
|-
|-
| '''Alter Key noch Tage''' || Nur beim Schlüsseltausch: wie lange der bisherige API-Key daneben gültig bleibt
| Client-Zertifikat passt nicht zu '''mTLS-Subject''' || '''401''' <code>CLIENT_CERT_INVALID</code>
|}
 
Unter '''Hinweise''' sammelt der Dialog, was fehlt oder fragwürdig ist - etwa ein Host, der auf den Server selbst zeigt und vom Gerät aus nicht erreichbar wäre. Solange eine Pflichtangabe fehlt, entsteht kein Code.
 
===Tasten im Dialog===
 
{| class="wikitable"
! Taste !! Funktion
|-
|-
| {{F2}} || QR-Code anzeigen, zum Abfotografieren mit dem Gerät
| JWT: kein Token gesendet || '''401''' <code>AUTH_REQUIRED</code>
|-
|-
| {{F3}} || Schlüssel tauschen: OBS erzeugt einen neuen API-Key. Der bisherige bleibt so viele Tage gültig, wie unter '''Alter Key noch Tage''' eingetragen sind - in dieser Zeit lesen die Geräte den neuen Code ein, ohne dass der Betrieb steht
| JWT: Anmeldung abgelehnt oder falscher Token-Typ || '''401''' <code>AUTH_FAILED</code>
|-
|-
| {{F4}} || Zugangscode in die Zwischenablage
| JWT: Token abgelaufen oder Sitzung gesperrt || '''401''' <code>AUTH_EXPIRED</code>
|-
| {{Key|Esc}} || Dialog schliessen
|}
|}


{{Achtung|Der Zugangscode enthält den API-Key im Klartext. Geben Sie ihn nur an das Gerät weiter, für das er bestimmt ist, und verschicken Sie ihn nicht über offene Kanäle.}}
Den genauen Grund einer Abweisung nennt das Protokoll. Alle Fehlercodes und die empfohlene Reaktion des Clients beschreibt [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]].
 
==Listen-Funktionen==
 
In der Zugänge-Liste (allein):
 
* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F6''' - Zugangscode für eine OBS-Smart-App
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang
 
Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):


* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
== Siehe auch ==
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugangscode und Zertifikats-Pin|Zugangscode und Zertifikats-Pin]]
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]

Version vom 17. November 2026, 06:59 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> (gueltig 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, 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 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.

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 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.

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 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.

Siehe auch