OBS/Kostenpflichtige Module/RESTServer/Zugaenge
- A Preise aktualisieren
- C Personen übertragen
- E Kategorien verwalten
- G Kataloge verwalten
- I Merkliste übertragen
- K Varianten übertragen
- L Artikelvarianten übertragen
- M Referenzarten übertragen
- N Lagerbestände verwalten
- U Bestellungen einlesen
- V leere Passworte füllen
- W Update-Informationen zurücksetzen
- X Konfiguration
- Z Protokoll
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
| Feld | Beschreibung |
|---|---|
| Name | Sprechender Name, erscheint im Protokoll und der Statistik |
| Aktiv | Inaktive Zugaenge werden bei der Authentifizierung mit 403 abgewiesen |
| API-Key | Eindeutiger Schluessel, den der Konsument im HTTP-Header apikey senden muss. Per Schluesselsymbol generierbar |
| Host | Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht ueberein, wird mit 403 abgelehnt |
| CORS-Origins | Liste erlaubter Origins fuer Browser-Aufrufe, mehrere durch ; getrennt |
| 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-Endpunkt | Adresse, ueber die der JWT-Token bezogen wird (z.B. oauth), darf keinen / enthalten |
| JWT-Key | Geheimer Schluessel zur Signierung/Verifikation, per Schluesselsymbol generierbar |
| JWT-Exp | Gueltigkeitsdauer eines ausgestellten Tokens in Minuten |
API-Key
Der API-Key ist die Basis-Authentifizierung. Der Client uebergibt 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 oeffentliche Endpunkte ohne Authentifizierung realisieren.
Host-Beschraenkung
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.
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:
- 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.
- Der eigentliche Request wird gegen die Origin-Liste des aktuell verwendeten Zugangs geprueft.
- Stimmt das Origin nicht, wird mit 403 Origin nicht erlaubt fuer 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.
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 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:
- status = 1 bei Erfolg, 9 bei Misserfolg
- error = Fehlertext (bei status=9)
- _OBS_JWT_ID, _OBS_JWT_SUBJECT, _OBS_JWT_AUDIENCE fuer die JWT-Claims (optional)
zurueckliefert. Bei Erfolg signiert der Server einen Token (HS256, Issuer OBS REST-Server, Lebenszeit gemaess 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 Verfuegung.
Details und ein vollstaendiges Beispiel siehe Scripting.
mTLS-Subject-Pruefung
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).
Beispiele fuer 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 ueber dieselbe CA klar voneinander trennen.
Listen-Funktionen
In der Zugaenge-Liste (allein):
- Einfg - neuer Zugang
- Return - Zugang bearbeiten
- F4 - Sortierung
- F7 - JWT-Authentifizierungs-Skript bearbeiten
- F8 - Statistik fuer den Zugang
Aus der Endpunkt-Liste via F6 geoeffnet (Auswahl fuer Berechtigung):
- F2 - markierte Zugaenge dem Endpunkt zuordnen
- F5 - Zugang in der Liste markieren / Markierung aufheben