Konfigurieren Sie mehrere Instanzen von RestFrontage hinter IIS ARR

• Nicht definierter Typ

Dieser Leitfaden beschreibt, wie man IIS ARR so konfiguriert, dass Anfragen über mehrere RestFrontage-Instanzen verteilt und das ursprüngliche HTTPS an diese weitergeleitet werden. Das Beispiel verwendet zwei Instanzen auf einer einzigen Maschine; das Prinzip gilt für mehr Instanzen, die auf einem oder mehreren Maschinen gehostet werden. Jede Instanz muss die Proxy-Adresse so akzeptieren, wie sie sie sieht

Diese Dokumentation richtet sich an Integratoren und Administratoren, die Immersive RestFrontage hinter einem Reverse-Proxy bereitstellen. Sie beschreibt, wie man das ursprüngliche HTTPS-Protokoll erkennt, wie vertrauenswürdige Proxys konfiguriert werden und welche Prüfungen vor der Bereitstellung durchgeführt werden sollten.

Namen portail.example.com, application-noeud-1 und application-noeud-2, und die Adressen und Ports in den Beispielen sind anschaulich. Ersetzen Sie sie durch die Werte Ihrer Installation.

1. Verständnis der Rolle des Reverse Proxy

Ein Reverse-Proxy empfängt Anfragen von Benutzern und leitet diese dann an RestFrontage weiter. Dazu gehören HTTPS-Eingabe, Routing zu Anwendungen und die Verteilung von Anfragen auf mehrere Instanzen.

Wenn der Proxy eine Anfrage über HTTPS erhält und sie über HTTP an RestFrontage weiterleitet, muss die Anwendung das vom Besucher verwendete Protokoll kennen. Andernfalls kann sie zurück zu HTTPS umleiten, eine Adresse mit dem inneren Port einer Instanz erzeugen oder eine Redirect-Schleife auslösen.

flowchart TB
    U["Utilisateur"]
    P["Reverse proxy"]
    A["Immersive RestFrontage"]

    U -->|"HTTPS : connexion publique chiffrée"| P
    P -->|"HTTP : liaison interne autorisée<br/>X-Forwarded-Proto: https"| A

Konfigurierbare Reverse-Proxy-Unterstützung ermöglicht es RestFrontage, diese Informationen zu erkennen, wenn sie von einem explizit autorisierten Proxy stammen.

2. Standardumfang und Verhalten

Die Funktionalität ist standardmäßig deaktiviert. Ohne Abschnitt ReverseProxy, oder mit Enabled à falsewird keine zusätzliche Verarbeitung in die Abfragepipeline aufgenommen. Die bereits vorhandene IIS-Integration behält ihr Verhalten bei.

Wenn aktiviert, liest die Funktion nur X-Forwarded-Proto um festzustellen, ob die ursprüngliche Anfrage HTTP oder HTTPS verwendet. Diese Verarbeitung erfolgt vor HSTS, HTTPS-Umleitung und Authentifizierung.

Es bewahrt die anderen Informationen in der Anfrage: Hostname, Anruferadresse, Pfad und Benutzeridentität. Header X-Forwarded-For, X-Forwarded-Host und X-Forwarded-Prefix sind durch diese Konfiguration nicht aktiviert.

3. Konfigurieren Sie vertrauenswürdige Proxys

3.1 Voraussetzungen

• Haben Sie eine aktuelle Version von RestFrontage für das ReverseProxy.
• Identifizieren Sie die IP-Adresse, unter der jeder unmittelbare Proxy von der Anwendung angezeigt wird.
• Sie haben die notwendigen Rechte, um die Konfiguration von RestFrontage und dem Proxy zu ändern.
• Planen Sie den Neustart jeder betroffenen Instanz nach der Änderung ein.

3.2 Verfügbare Einstellungen

Füge den nächsten Abschnitt zur Wurzel der Datei hinzu appsettings.json der Installation, wobei die übrigen Abschnitte beibehalten werden:

{
  "ReverseProxy": {
    "Enabled": false,
    "KnownProxies": []
  }
}

Parameter	Default	Beschreibung
ReverseProxy:Enabled	false	Ermöglicht die Erkennung des Ursprungsprotokolls, das von deklarierten Proxys übertragen wird.
ReverseProxy:KnownProxies	Leere Liste	Genaue IP-Adressen der unmittelbaren Proxys, die autorisiert sind, diese Informationen zu übertragen.

Wenn Enabled ist es wert true, die Liste muss mindestens eine gültige IPv4- oder IPv6-Adresse enthalten. DNS-Namen, CIDR-Bereiche, Wildcards und generische Zuhörer wie 0.0.0.0 und :: werden nicht akzeptiert.

Lokale Schleifenadressen werden nicht implizit vertraut: explizit hinzufügen 127.0.0.1 oder ::1 falls verwendet. IPv4-Darstellungen, die auf IPv6 abgebildet sind, werden ebenfalls erkannt.

Eine aktivierte Konfiguration mit unbekannter Einstellung, einer leeren Liste oder einer ungültigen Adresse verhindert das Booten mit einem Konfigurationsfehler. Es gibt keinen Fallback, der alle Proxys erlaubt. Wenn die Funktion deaktiviert ist, werden die ungenutzten Einstellungen in diesem Abschnitt nicht validiert.

3.3 Proxy auf demselben Rechner installiert

Für einen Proxy, der RestFrontage über die lokale Schleife kontaktiert:

{
  "ReverseProxy": {
    "Enabled": true,
    "KnownProxies": [ "127.0.0.1", "::1" ]
  }
}

3.4 Proxy auf einem anderen Rechner installiert

Für einen Proxy, dessen Quelladresse von der Anwendung gesehen wird, zum Beispiel gilt: 10.20.0.10 :

{
  "ReverseProxy": {
    "Enabled": true,
    "KnownProxies": [ "10.20.0.10" ]
  }
}

Wenn es mehrere Proxys gibt, die die Anwendung direkt kontaktieren können, geben Sie deren Adressen in derselben Liste an. Verwenden Sie keine Benutzeradressen oder die öffentliche Adresse des Portals, es sei denn, die öffentliche Adresse des Portals ist tatsächlich die Quelladresse des Proxys, wie sie von RestFrontage gesehen wird.

3.5 Änderungen durchsetzen

Die Konfiguration wird beim Start gelesen. Unter IIS wird der Anwendungspool jeder betroffenen Instanz nach der Änderung wiederverwendet. Für einen anderen Hosting-Modus wird der Dienst neu gestartet, der RestFrontage hostet.

Umgebungsvariablen können ebenfalls folgende Werte liefern:

Variable	Beispielwert
ReverseProxy__Enabled	true
ReverseProxy__KnownProxies__0	127.0.0.1
ReverseProxy__KnownProxies__1	::1

4. Proxy-Routing vorbereiten

Der Proxy muss den öffentlichen Hostnamen im Header weitergeben Host, weil dieses Merkmal nicht wiederherstellbar ist X-Forwarded-Host.

Für eine Anfrage, die über HTTPS empfangen wird, muss sie festlegen X-Forwarded-Proto à https. Für eine öffentliche Anfrage, die über HTTP empfangen wird, muss sie entweder den Besucher zu HTTPS umleiten oder das eigentliche Protokoll passieren.

Begrenze den Zugriff auf die internen Bindings von RestFrontage auf die in der Architektur vorgesehenen Komponenten. Wenn ein Host den Server mit dem Proxy teilt, können seine lokalen Prozesse auch Anfragen aus der lokalen Schleife stellen, sodass der Server Teil des vertrauenswürdigen Perimeters ist.

4.1 Mehrere Relais oder bestehende IIS-Integration

RestFrontage berücksichtigt nur den rechten Wert von X-Forwarded-Proto, entsprechend den vom unmittelbaren Proxy übermittelten Informationen. Dieser Mechanismus rekonstruiert nicht den gesamten Pfad durch mehrere Proxys und ändert auch nicht die bereits vom IIS verwendeten Header-Weiterleitungsoptionen

Da IIS nicht verarbeitet ist, könnten einige Header bereits verarbeitet worden sein, bevor sie die RestFrontage-Pipeline erreichten. Bei mehreren Relays überprüfen Sie die tatsächlich von der Anwendung erhaltenen Informationen, bevor Sie die erlaubten Adressen definieren. Eine Liste mehrerer erlaubter Proxys stellt für sich genommen nicht die Beschreibung einer Relay-Kette dar.

5. Beispiel mit IIS ARR und zwei lokalen Instanzen

Dieses Beispiel zeigt zwei RestFrontage-Anwendungen auf einer einzigen Windows-Maschine. Jede Anwendung verwendet ihren eigenen IIS-Pool. Die ARR-Ingress-Seite empfängt Benutzer auf einer gemeinsamen HTTPS-Adresse.

Element	Illustrativer Wert
Öffentliche Ansprache	https://portail.example.com
ARR-Standortbindung	HTTPS-Port 443, Zertifikat, gültig für den öffentlichen Namen
Instanz 1	HTTP, 127.0.0.1:18081
Instanz 2	HTTP, 127.0.0.1:18082
Lokales Alias von Instanz 1	application-noeud-1
Lokales Alias von Instanz 2	application-noeud-2

5.1 Bereite Bindungen und Aliase vor

1. Überprüfen Sie, dass die Ports 18081 und 18082 sind verfügbar.
2. Fügen Sie eine HTTP-Bindung hinzu 127.0.0.1:18081 auf die erste IIS-Seite, mit einem leeren Hostnamen.
3. Fügen Sie eine HTTP-Bindung hinzu 127.0.0.1:18082 am zweiten IIS-Standort, mit leerem Hostnamen.
4. Behalten Sie alle HTTPS-Links für den direkten Zugriff auf.
5. Füge beide Aliase zu den C:\Windows\System32\drivers\etc\hosts, von einem Editor, der als Administrator fungiert.

127.0.0.1 application-noeud-1
127.0.0.1 application-noeud-2

ARR verwendet die Namen der Ziele, um die Mitglieder der Farm zu unterscheiden. Zwei Aliase werden verwendet, um zwei Anwendungen auf demselben Server auf verschiedenen Ports darzustellen.

5.2 Instanzen konfigurieren und farmen

1. Aktivieren ReverseProxy auf beiden Instanzen mit den notwendigen lokalen Schleifenadressen.
2. Recycele beide Anwendungspools.
3. In ARR fügen Sie das hinzu application-noeud-1 auf der Farm mit dem HTTP-Port 18081.
4. In den Warenkorb legen application-noeud-2 mit HTTP-Port 18082.
5. Konfigurieren Sie die HTTPS-Ingress-Seite so, dass sie den öffentlichen Hostnamen und die Weitergabe beibehält X-Forwarded-Proto: https zu HTTP-Zielen.
6. Beschränken Sie die Routing-Regel auf den vorgesehenen Eintrittsstandort für diese Anwendung.

5.3 Besonderheiten des Multi-Instanz-Tests

Um Speicher-Caches zu testen, verwenden Sie zwei separate IIS-Pools, um zwei unabhängige Prozesse zu erhalten. Gehen Sie auch direkt zu jeder Instanz, um genau zu wissen, welche Instanz den Lesen oder die Änderung empfängt.

Wenn das Szenario einen Wechsel von einer Instanz zur anderen hinter ARR erfordert, deaktivieren Sie die Client-Affinität während des Tests. Deaktivieren Sie außerdem den ARR-Cache, um den Anwendungscache zu beobachten. Diese Testeinstellungen definieren nicht automatisch die Konfiguration, die in der Produktion erhalten bleiben soll.

Das Teilen von Authentifizierung, Datenschutzschlüsseln, Sitzungen und verteilten Caches ist Teil der Multi-Instanz-Konfiguration der Anwendung. Die ReverseProxy führt dieses Teilen nicht durch. Zwei Instanzen auf einer einzigen Maschine bleiben gleichzeitig nicht verfügbar, wenn diese Maschine herunterfährt.

6. Kontrollbetrieb

Die folgenden Befehle beziehen sich auf PowerShell auf dem Rechner, der das On-Premises-Beispiel hostet. Sie zeigen die Antwortheader an, ohne den Weiterleitungen zu folgen.

6.1 Überprüfen Sie HTTP Direct Access

curl.exe -sS -D - -o NUL http://application-noeud-1:18081/

Diese Anfrage deklariert kein ursprüngliches HTTPS. Wenn die HTTPS-Umleitung und sein Zielport auf der Instanz konfiguriert sind, muss die Weiterleitung aktiv bleiben. Aktivieren ReverseProxy sollte diesen HTTP-Zugriff nicht allein in HTTPS umwandeln.

6.2 Überprüfung der Erkennung des ursprünglichen Protokolls

curl.exe -sS -D - -o NUL -H "X-Forwarded-Proto: https" -H "Host: portail.example.com" http://application-noeud-1:18081/
curl.exe -sS -D - -o NUL -H "X-Forwarded-Proto: https" -H "Host: portail.example.com" http://application-noeud-2:18082/

Diese Anfragen stammen von der ausdrücklich erlaubten lokalen Schleife. Sie müssen die Anwendung ohne HTTP-Weiterleitung zum internen HTTPS-Port einer Instanz erreichen. Eine Weiterleitung zu /Login oder /setup Je nach Zustand der Installation kann das normal sein.

6.3 Validierung des öffentlichen Zugangs

• Öffnen Sie die öffentliche Adresse und überprüfen Sie deren HTTPS-Zertifikat.
• Überprüfen Sie, dass Weiterleitungen den öffentlichen Namen ohne Aliase oder interne Ports behalten.
• Melden Sie sich an und durchstöbern Sie die von Kunden genutzten Seiten und Funktionen.
• Überprüfen Sie Cookies und die Authentifizierungskontinuität gemäß der gewählten Multi-Instanz-Konfiguration.
• Überprüfen Sie in den Protokollen oder Überwachungstools, welche Instanzen die Anfragen erhalten.
• Für Cache-Tests modifizieren Sie ein Objekt durch eine Instanz und spielen es dann in der anderen erneut ab und beobachten Sie die erwartete Propagation.

7. Diagnose einer falschen Konfiguration

Symptom	Prüfungen
Die App startet nach der Aktivierung nicht mehr	Überprüfen Sie die Gültigkeit des JSON, der Parameternamen und des Vorhandenseins mindestens einer gültigen IP-Adresse in KnownProxies.
Eine Weiterleitung zu einem internen Port bleibt bestehen	Verifizieren Sie die bereitgestellte Version, Sektionsaktivierung, Pool-Recycling, übertragenen Header und Proxy-Quelladresse, die von RestFrontage gesehen werden.
Eine Umleitungsschleife erscheint	Überprüfen Sie das vom Proxy deklarierte Protokoll und den Anwendungsbereich der Routing-Regel, insbesondere auf internen Standorten.
Eine interne Adresse erscheint in einer Weiterleitung	Überprüfen Sie, dass der Proxy die Host öffentlich. Die ReverseProxy behandelt nicht X-Forwarded-Host.
Ein Zertifikatsfehler erscheint	Überprüfen Sie den Namen, der vom Zertifikat des betreffenden HTTPS-Links abgedeckt ist. Die ReverseProxy ändert nicht die Zertifikatsvalidierung.
Sitzungen gehen verloren, wenn man die Instanzen wechselt	Überprüfen Sie die Konfiguration der Authentifizierung, des Datenschutzes und der Sitzungsspeicherung.
Eine Änderung bleibt in einer anderen Instanz unsichtbar	Überprüfen Sie Anwendungscaches, verteilte Ungültigkeit, Ereignispropagation und jeden Proxy-Cache.

8. Zur vorherigen Konfiguration zurückkehren

Übergabe ReverseProxy:Enabled à false, und dann die IIS-Pools recyceln oder die betroffenen Dienste neu starten.

Wenn der Proxy weiterhin Anfragen über HTTP weiterleitet, können Anwendungen auf ihre HTTPS-Ports umleiten. Planen Sie das entsprechende Routing, bevor Sie diese Unterstützung bei einer Live-Installation deaktivieren.

Weitere Quellen

• ASP.NET Core hinter einem Proxy oder Load Balancer
• Verarbeitung von Headern von unbekannten Proxys
• IIS ARR mit mehreren Anwendungen auf einer Maschine