Zum Inhalt springen

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

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
MINERVA-Rademacker (Diskussion | Beiträge)
Weiterleitung auf Pflege#Zugang, Inhalt in die Seite Pflege übernommen [Volltext ersetzt]
Markierung: Neue Weiterleitung
 
(14 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
#WEITERLEITUNG [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Zugang]]
 
=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==
 
{| class="wikitable"
! 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  || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; 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:
 
# 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.
 
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 die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh):
 
===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)
* ''_OBS_JWT_CLAIM_<name>'' 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)
 
zurückliefert. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:
 
{"token": "eyJhbGciOi...", "serverTime": "2026-06-29T15:30:12+02:00"}
 
===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.
 
===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/
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'') und ruft im selben Skript die Methode '''Refresh''' auf. Das Skript prÜft seine Sperrtabelle, rotiert das Refresh-jti und liefert neue Claims. Der Server antwortet mit einem rotierten Paar ''{"token","refreshToken","serverTime"}''. Ein bereits benutztes (rotiertes) Refresh-Token wird mit 401 abgelehnt.
Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|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 (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=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de
 
Mit '''CN=client-prod.kunde.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=Kunde GmbH;CN=client-prod.kunde.de''.
 
==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

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