OBS/Kostenpflichtige Module/RESTServer/Zugaenge: Unterschied zwischen den Versionen

Aus OBS Wiki
Zur Navigation springen Zur Suche springen
(Die Seite wurde neu angelegt: „{{Kostenpflichtige Module}} =Zugaenge= Ein '''Zugang''' (Account) ist der Kanal, ueber den ein externer Konsument den REST-Server anspricht. Er buendelt API-Key, Host-Beschraenkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Pruefung. ==Aufruf== '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugaenge''' ==Felder== {| class="wikitable" ! Feld !! Beschreibung |- | Name || Sprechender Name,…“)
Keine Bearbeitungszusammenfassung
 
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Kostenpflichtige Module}}


=Zugaenge=
=Zugänge=


Ein '''Zugang''' (Account) ist der Kanal, ueber den ein externer Konsument den REST-Server anspricht. Er buendelt API-Key, Host-Beschraenkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Pruefung.
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.


==Aufruf==
==Aufruf==


'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugaenge'''
'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''


==Felder==
==Felder==
Zeile 16: Zeile 16:
| Name          || Sprechender Name, erscheint im Protokoll und der Statistik
| Name          || Sprechender Name, erscheint im Protokoll und der Statistik
|-
|-
| Aktiv        || Inaktive Zugaenge werden bei der Authentifizierung mit 403 abgewiesen
| Aktiv        || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
|-
| API-Key      || Eindeutiger Schluessel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schluesselsymbol generierbar
| 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 ueberein, wird mit 403 abgelehnt
| Host          || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
|-
| CORS-Origins  || Liste erlaubter Origins fuer Browser-Aufrufe, mehrere durch '';'' getrennt
| CORS-Origins  || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt
|-
|-
| mTLS-Subject  || Erwarteter Substring im Client-Zertifikat-Subject (nur sinnvoll bei mTLS-Servern)
| mTLS-Subject  || Erwarteter Substring im Client-Zertifikat-Subject (nur sinnvoll bei mTLS-Servern)
|-
|-
| JWT          || Schalter, ob fuer diesen Zugang ein JWT-Token noetig ist
| JWT          || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
|-
| JWT-Endpunkt  || Adresse, ueber die der JWT-Token bezogen wird (z.B. ''oauth''), darf keinen ''/'' enthalten
| JWT-Endpunkt  || Adresse, über die der JWT-Token bezogen wird (z.B. ''oauth''), darf keinen ''/'' enthalten
|-
|-
| JWT-Key      || Geheimer Schluessel zur Signierung/Verifikation, per Schluesselsymbol generierbar
| JWT-Key      || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
|-
| JWT-Exp      || Gueltigkeitsdauer eines ausgestellten Tokens in Minuten
| JWT-Exp      || Gültigkeitsdauer eines ausgestellten Tokens in Minuten
|}
|}


==API-Key==
==API-Key==


Der API-Key ist die Basis-Authentifizierung. Der Client uebergibt ihn im HTTP-Header:
Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:


  apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12
  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 oeffentliche Endpunkte ohne Authentifizierung realisieren.
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 fuer bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschraenkung oder CORS-Beschraenkung betrieben werden.}}
{{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.}}


==Host-Beschraenkung==
==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-Aufloesung auf diese IP zeigt. DNS-Aufloesungen werden 5 Minuten gecached.
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.


==CORS==
==CORS==
Zeile 59: Zeile 59:
Ablauf:
Ablauf:


# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prueft das Origin gegen die globale Origin-Liste aller Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# 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 geprueft.
# Der eigentliche Request wird gegen die Origin-Liste des aktuell verwendeten Zugangs geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt fuer Account ...'' abgelehnt.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.


Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH''. Erlaubte Header: ''Content-Type, apikey, Authorization, Accept''. Diese Werte sind systemseitig festgelegt und werden in der Preflight-Antwort zurueckgegeben.
Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH''. Erlaubte Header: ''Content-Type, apikey, Authorization, Accept''. Diese Werte sind systemseitig festgelegt und werden in der Preflight-Antwort zurückgegeben.


==JWT-Authentifizierung==
==JWT-Authentifizierung==
Zeile 77: Zeile 77:
  Body:  {"username":"...", "password":"..."}
  Body:  {"username":"...", "password":"..."}


Der Server fuehrt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Funktion ''Authenticate'' bereitstellen, die ein JSON-Objekt mit:
Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Funktion ''Authenticate'' bereitstellen, die ein JSON-Objekt mit:


* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' fuer die JWT-Claims (optional)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)


zurueckliefert. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemaess JWT-Exp) und antwortet:
zurückliefert. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:


  {"token": "eyJhbGciOi..."}
  {"token": "eyJhbGciOi..."}
Zeile 95: Zeile 95:
         Authorization: Bearer eyJhbGciOi...
         Authorization: Bearer eyJhbGciOi...


Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew). Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfuegung.
Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew). Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.


Details und ein vollstaendiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].


==mTLS-Subject-Pruefung==
==mTLS-Subject-Prüfung==


Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prueft der Server zusaetzlich zur Standard-mTLS-Validierung, ob der Subject-DN des Client-Zertifikats den hinterlegten Text enthaelt (case-insensitiv, Substring-Match).
Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des Client-Zertifikats den hinterlegten Text enthält (case-insensitiv, Substring-Match).


Beispiele fuer Subject-Strings im Cert:
Beispiele für Subject-Strings im Cert:


  /C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
  /C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
  /C=DE/O=Kunde GmbH/CN=client-test.kunde.de
  /C=DE/O=Kunde GmbH/CN=client-test.kunde.de


Mit '''CN=client-prod''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert wird mit 401 abgewiesen. Damit lassen sich verschiedene Konsumenten ueber dieselbe CA klar voneinander trennen.
Mit '''CN=client-prod''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert wird mit 401 abgewiesen. Damit lassen sich verschiedene Konsumenten über dieselbe CA klar voneinander trennen.


==Listen-Funktionen==
==Listen-Funktionen==


In der Zugaenge-Liste (allein):
In der Zugänge-Liste (allein):


* '''Einfg''' - neuer Zugang
* '''Einfg''' - neuer Zugang
Zeile 118: Zeile 118:
* '''F4''' - Sortierung
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik fuer den Zugang
* '''F8''' - Statistik für den Zugang


Aus der Endpunkt-Liste via F6 geoeffnet (Auswahl fuer Berechtigung):
Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):


* '''F2''' - markierte Zugaenge dem Endpunkt zuordnen
* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

Aktuelle Version vom 19. Mai 2026, 07:11 Uhr

Kostenpflichtige Module

Internet-Shop
Der modified ECommerce Shop
Shop-Menü
Automatische Vorgänge
modified eCommerce 2.0
Der Büroring-ShopV4
Einrichtung
Eigene Artikel
brShop24
Einstellungen und Automatiken
Funktionen
Preislisten
Preislistenverwaltung
F10 Weitere Funktionen
Automatiken Kommandos
ZUGFeRD
Factoring
UPS
DHL
IMS Professional
TAPI
SMS
Fleet Management
Mehrlager-Verwaltung
Mehrsprachen Modul
Multilanguage Modul
Einfache Produktionsnachverfolgung
DMS - Dokumenten Management System
DMS Dokumente
Tasten und Schaltflächen
F10 Weit.
E DMS Definitionen
QR Zeiterfassung
EVA Marketing Tool
Technikersteuerung
Termin-Projekte
Edifact-Schnittstelle
Backup Überwachung Email
Anlagenbuchhaltung
OBS Geo Daten
DeliSprint / DPD
Filialen
Auto-Waagen
Cashback
Moebelschnittstelle
Tourenplanung
Tourenplanung
Dokumenten Manager
DocuWare-Schnittstelle
OFML-Kalkulation
Pascom
Versicherungsschaden
Gutschriftsanzeigen
OCPP Ladestationen
Kameraverwaltung
DataInOut
REST-Schnittstelle
Beispiele
Sammelverträge
Craftboxx
OpenMasterData / IDS
Sammelpositionen


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.

Aufruf

Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge

Felder

Feld Beschreibung
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
mTLS-Subject Erwarteter Substring im Client-Zertifikat-Subject (nur sinnvoll bei mTLS-Servern)
JWT Schalter, ob für diesen Zugang ein JWT-Token nötig ist
JWT-Endpunkt Adresse, über die der JWT-Token bezogen wird (z.B. oauth), darf keinen / enthalten
JWT-Key Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
JWT-Exp Gültigkeitsdauer eines ausgestellten Tokens in Minuten

API-Key

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.

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.

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.kunde.de;https://test.kunde.de;https://localhost:8080

Ablauf:

  1. 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.
  2. Der eigentliche Request wird gegen die Origin-Liste des aktuell verwendeten Zugangs geprüft.
  3. Stimmt das Origin nicht, wird mit 403 Origin nicht erlaubt für Account ... abgelehnt.

Erlaubte Methoden: GET, POST, PUT, DELETE, PATCH. Erlaubte Header: Content-Type, apikey, Authorization, Accept. Diese Werte sind systemseitig festgelegt und werden in der Preflight-Antwort zurückgegeben.

JWT-Authentifizierung

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind zwei Phasen zu durchlaufen:

Phase 1: Token-Bezug

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.: 

POST https://api.meinserver.de/oauth/
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 Funktion Authenticate bereitstellen, die ein JSON-Objekt mit:

  • status = 1 bei Erfolg, 9 bei Misserfolg
  • error = Fehlertext (bei status=9)
  • _OBS_JWT_ID, _OBS_JWT_SUBJECT, _OBS_JWT_AUDIENCE für die JWT-Claims (optional)

zurückliefert. Bei Erfolg signiert der Server einen Token (HS256, Issuer OBS REST-Server, Lebenszeit gemäß JWT-Exp) und antwortet: 

{"token": "eyJhbGciOi..."}

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). Im Skript stehen die Claims als Parameter _OBS_JWT_ID, _OBS_JWT_SUBJECT und _OBS_JWT_AUDIENCE zur Verfügung.

Details und ein vollständiges Beispiel siehe Scripting.

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 Client-Zertifikats den hinterlegten Text enthält (case-insensitiv, Substring-Match).

Beispiele für Subject-Strings im Cert: 

/C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de

Mit CN=client-prod im Feld wird genau das prod-Cert akzeptiert, das test-Cert wird mit 401 abgewiesen. Damit lassen sich verschiedene Konsumenten über dieselbe CA klar voneinander trennen.

Listen-Funktionen

In der Zugänge-Liste (allein):

  • Einfg - neuer Zugang
  • Return - Zugang bearbeiten
  • F4 - Sortierung
  • 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
  • F5 - Zugang in der Liste markieren / Markierung aufheben
Abgerufen von „http:///index.php?title=OBS/Kostenpflichtige_Module/RESTServer/Zugaenge&oldid=64461“