|
|
| (5 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt) |
| Zeile 1: |
Zeile 1: |
| {{Kostenpflichtige Module}}
| | #WEITERLEITUNG [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Server-Profil]] |
| | |
| =Server-Profile=
| |
| | |
| Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.
| |
| | |
| Typische Einsatzfälle für mehrere Profile:
| |
| | |
| * Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
| |
| * Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
| |
| * Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.
| |
| | |
| ==Aufruf==
| |
| | |
| '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''
| |
| | |
| ==Felder des Server-Profils==
| |
| | |
| {| class="wikitable"
| |
| ! Feld !! Beschreibung
| |
| |-
| |
| | Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
| |
| |-
| |
| | Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
| |
| |-
| |
| | Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
| |
| |-
| |
| | zusätzliche Infos || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
| |
| |-
| |
| | kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
| |
| |-
| |
| | mTLS-Modus aktiv || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
| |
| |-
| |
| | Zertifikat (cert) || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
| |
| |-
| |
| | Schlüssel (key) || PEM-Inhalt des privaten Schlüssels
| |
| |-
| |
| | Root-Zertifikat (ca) || PEM-Inhalt des CA-Zertifikats, gegen das '
| |
| |-
| |
| | Rate-Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
| |
| |-
| |
| | Erfolgsanfragen || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
| |
| |-
| |
| | Fehlanfragen || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
| |
| |-
| |
| | Anfragen || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
| |
| |-
| |
| | max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
| |
| |-
| |
| | max. Anfragen || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
| |
| |-
| |
| | keine Kompression || Antworten dieses Profils werden '''nicht''' gepackt (<code>rsv_no_gzip</code>). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über <code>Accept-Encoding</code> annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte '''Anfragen''' nimmt der Server weiterhin entgegen
| |
| |}
| |
| | |
| {{Hinweis|''max. Verbindungen'' und ''max. Anfragen'' sind die beiden
| |
| '''Lastgrenzen''' des Profils. Davon zu unterscheiden sind die festen Grenzen der
| |
| persistenten Verbindungen - 10 Sekunden Leerlauf, 100 Anfragen je Verbindung -,
| |
| die nicht der Last dienen, sondern der Hygiene und nicht einstellbar sind. Siehe
| |
| [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Persistente | |
| Verbindungen.}}
| |
| | |
| Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.
| |
| | |
| ==Modi==
| |
| | |
| {| class="wikitable"
| |
| ! Modus !! Voraussetzungen !! Anwendung
| |
| |-
| |
| | '''Standard-TLS''' || Zertifikat + Schlüssel || Für den Betrieb, auch wenn der Server nur intern, hinter einem Reverse-Proxy oder per VPN erreichbar ist
| |
| |-
| |
| | '''mTLS''' || Zertifikat + Schlüssel + Root-Zert. || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
| |
| |-
| |
| | '''Plain-HTTP''' || Haken ''kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
| |
| |}
| |
| | |
| Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
| |
| TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
| |
| und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
| |
| Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
| |
| keine Verarbeitung aus.
| |
| | |
| {{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Zertifikat und Schlüssel gar nicht erst hoch. Bei aktiver Erneuerung trägt der Dienst beides selbst ein. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}
| |
| | |
| ==TLS-Version, Cipher und Zertifikats-Rotation==
| |
| | |
| * '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
| |
| * '''HSTS:''' Jede Antwort eines TLS-Profils trägt ''Strict-Transport-Security: max-age=31536000; includeSubDomains''. Ein Browser spricht die Adresse damit ein Jahr lang nur noch über HTTPS an. Beim Profil ''Kein SSL'' wird der Header bewusst '''nicht''' gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
| |
| * '''Rotation:''' Bei '''automatischer Erneuerung''' tauscht der Dienst das Zertifikat selbst und startet dabei nur das betroffene Server-Profil neu; die übrigen Profile und der Dienst laufen weiter. Bei manueller Pflege ändern Sie die PEM-Inhalte und starten den REST-Dienst neu - bis dahin läuft das alte Zertifikat weiter.
| |
| * '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.
| |
| ==Automatische Zertifikatserneuerung==
| |
| | |
| Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Prüfarten, Voraussetzungen, Einrichtung, Ablauf und Konsolenbefehle beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]].
| |
| | |
| ===Felder===
| |
| | |
| Registerkarte '''4 Zertifikaterneuerung''':
| |
| | |
| {| class="wikitable"
| |
| ! Feld !! Beschreibung
| |
| |-
| |
| | Automatische Erneuerung || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = nur für Testsysteme, siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Testbetrieb|Testbetrieb]]
| |
| |-
| |
| | Zertifikatsname (FQDN) || Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
| |
| |-
| |
| | Kontakt bei der CA || Optional. Die Zertifizierungsstelle schickt an diese Adresse Warnungen, wenn ein Zertifikat abzulaufen droht
| |
| |-
| |
| | Zertifikat gültig bis || Ablaufdatum des aktiven Zertifikats
| |
| |-
| |
| | Testzertifikat aus Staging || Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt
| |
| |-
| |
| | Zustand || ''idle'' = nichts zu tun, ''pending'' = Vorgang läuft, ''error'' = letzter Versuch fehlgeschlagen
| |
| |-
| |
| | Letzte Meldung || Ergebnis des letzten Vorgangs - im Störungsfall das erste Feld, in das Sie sehen
| |
| |-
| |
| | Gesperrt bis || Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht
| |
| |-
| |
| | Letzter Selbsttest am || Zeitpunkt der letzten Prüfung über das Testsystem der Zertifizierungsstelle
| |
| |-
| |
| | Selbsttest bestanden || Ergebnis dieser Prüfung
| |
| |}
| |
| | |
| Die Felder ab ''Zertifikat gültig bis'' füllt der Dienst selbst; sie dienen der Anzeige.
| |
| | |
| Registerkarte '''5 DNS-Prüfung''':
| |
| | |
| {| class="wikitable"
| |
| ! Feld !! Beschreibung
| |
| |-
| |
| | Prüfart || ''http-01 (Port 80)'' oder ''dns-01 (DNS-Eintrag)'', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Welche Prüfart?|Welche Prüfart?]]
| |
| |-
| |
| | DNS-Anbieter || Nur dns-01: ''acme-dns'', ''Hetzner'', ''Cloudflare'' oder ''IONOS''
| |
| |-
| |
| | Adresse (acme-dns) || Nur acme-dns: Adresse der Instanz, beginnt mit <code>https://</code>
| |
| |-
| |
| | Benutzer (acme-dns) || Nur acme-dns: Benutzer des Kontos. Bleiben Benutzer, Schlüssel und Name leer, legt der Dienst das Konto selbst an
| |
| |-
| |
| | Schlüssel / API-Token || acme-dns: Passwort des Kontos. Hetzner und Cloudflare: API-Token. IONOS: API-Schlüssel in der Form <code>Präfix.Secret</code>
| |
| |-
| |
| | Name des TXT-Eintrags || Leer = <code>_acme-challenge.<Zertifikatsname></code>. Bei CNAME-Delegation das Ziel des CNAME, bei acme-dns die ''fulldomain'' des Kontos
| |
| |}
| |
| | |
| {{Hinweis|Die Zugangsdaten stehen im Klartext im Server-Profil. Verwenden Sie Token, die nur die nötige Zone ändern dürfen.}}
| |
| | |
| ==Rate-Limit je Profil==
| |
| | |
| Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
| |
| Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
| |
| aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.
| |
| | |
| Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
| |
| Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
| |
| '''IP-Adresse''' gezählt.
| |
| | |
| {{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
| |
| Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
| |
| API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
| |
| das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
| |
| Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
| |
| höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}
| |
| | |
| Dasselbe gilt hinter einem Reverse-Proxy: Alle Anfragen kommen dort von der IP-Adresse
| |
| des Proxys, und alle Konsumenten ohne API-Key teilen sich einen Zähler. Der Header
| |
| ''X-Forwarded-For'' ändert daran nichts, er wird nur protokolliert.
| |
| | |
| Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
| |
| '''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
| |
| Neustart wirksam.
| |
| | |
| ==Validierung beim Speichern==
| |
| | |
| Immer geprüft wird:
| |
| | |
| * Nr und Name sind vergeben, Nr liegt zwischen 1 und 99.
| |
| * Nr und Name sind eindeutig.
| |
| * Eingetragene Zertifikate und Schlüssel liegen im PEM-Format vor.
| |
| * Ein eingetragener Zertifikatsname enthält keine Adresse, keinen Port und keine Leerzeichen.
| |
| | |
| Nur bei '''aktivem''' Profil zusätzlich:
| |
| | |
| * Ohne ''kein SSL'' und ohne automatische Erneuerung sind Zertifikat und Schlüssel vorhanden.
| |
| * Bei ''mTLS-Modus aktiv'' ist das Root-Zertifikat vorhanden.
| |
| * Bei aktiver Erneuerung ist der Zertifikatsname vergeben, und ''kein SSL'' ist nicht gesetzt.
| |
| | |
| {{Hinweis|Ein '''nicht aktives''' Profil dürfen Sie unvollständig speichern - es wird beim Start des Dienstes nicht geladen. Was Sie eintragen, wird trotzdem auf Plausibilität geprüft.}}
| |
| | |
| ==Bindungen==
| |
| | |
| Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.
| |
| | |
| ===Aufruf===
| |
| | |
| In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.
| |
| | |
| ===Felder===
| |
| | |
| {| class="wikitable"
| |
| ! Feld !! Beschreibung
| |
| |-
| |
| | Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
| |
| |-
| |
| | Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
| |
| |-
| |
| | Aktiv || Bindung wird beim Server-Start geladen
| |
| |-
| |
| | Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
| |
| |}
| |
| | |
| ===Wirksamkeit===
| |
| | |
| Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.
| |
| | |
| ==Listen-Funktionen==
| |
| | |
| In der Server-Liste:
| |
| | |
| * '''Einfg''' - neues Server-Profil
| |
| * '''Return''' - vorhandenes Profil bearbeiten
| |
| * '''F4''' - Sortierung wählen
| |
| * '''F6''' - Bindungs-Liste des markierten Servers
| |