Aktuelle Version vom 29. Juni 2026, 11:09 Uhr

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

@@ Zeile 1: / Zeile 1: @@
 {{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==
-'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugaenge'''
+'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''
 ==Felder==
@@ Zeile 16: / Zeile 16: @@
 | 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  || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; 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==
-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
-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==
@@ Zeile 59: / Zeile 59: @@
 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==
-Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind zwei Phasen zu durchlaufen:
+Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh):
 ===Phase 1: Token-Bezug===
@@ Zeile 77: / Zeile 77: @@
   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
 * ''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)
+* ''_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)
-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...", "serverTime": "2026-06-29T15:30:12+02:00"}
 ===Phase 2: Token-Verwendung===
@@ Zeile 95: / Zeile 97: @@
           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]].
+===Phase 3: Token erneuern (Refresh)===
-==mTLS-Subject-Pruefung==
+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:
-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).
+ 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 fuer Subject-Strings im Cert:
+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''' 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.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 Zugaenge-Liste (allein):
+In der Zugänge-Liste (allein):
 * '''Einfg''' - neuer Zugang
@@ Zeile 118: / Zeile 129: @@
 * '''F4''' - Sortierung
 * '''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

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

Aktuelle Version vom 29. Juni 2026, 11:09 Uhr

Inhaltsverzeichnis

Zugänge

Aufruf

Felder

API-Key

Host-Beschränkung

CORS

JWT-Authentifizierung

Phase 1: Token-Bezug

Phase 2: Token-Verwendung

Phase 3: Token erneuern (Refresh)

mTLS-Subject-Prüfung

Listen-Funktionen

Navigationsmenü

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

Aktuelle Version vom 29. Juni 2026, 11:09 Uhr

Zugänge

Aufruf

Felder

API-Key

Host-Beschränkung

CORS

JWT-Authentifizierung

Phase 1: Token-Bezug

Phase 2: Token-Verwendung

Phase 3: Token erneuern (Refresh)

mTLS-Subject-Prüfung

Listen-Funktionen

Navigationsmenü

Suche