|
|
| (15 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 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 [[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
| |