Configurer plusieurs instances de RestFrontage derrière IIS ARR

• Undefined type

Ce guide explique comment configurer IIS ARR pour répartir les requêtes entre plusieurs instances de RestFrontage et leur transmettre le protocole HTTPS d’origine. L’exemple utilise deux instances sur une même machine ; le principe s’étend à davantage d’instances, hébergées sur une ou plusieurs machines. Chaque instance doit autoriser l’adresse du proxy telle qu’elle la voit

Cette documentation s'adresse aux intégrateurs et aux administrateurs qui déploient Immersive RestFrontage derrière un reverse proxy. Elle décrit la reconnaissance du protocole HTTPS d'origine, la configuration des proxys de confiance et les vérifications à réaliser avant la mise en service.

Les noms portail.example.com, application-noeud-1 et application-noeud-2, ainsi que les adresses et ports des exemples, sont illustratifs. Remplacez-les par les valeurs de votre installation.

1. Comprendre le rôle du reverse proxy

Un reverse proxy reçoit les requêtes des utilisateurs puis les transmet à RestFrontage. Il peut notamment assurer l'entrée HTTPS, le routage vers les applications et la répartition des requêtes entre plusieurs instances.

Lorsque le proxy reçoit une requête en HTTPS et la transmet à RestFrontage en HTTP, l'application doit connaître le protocole utilisé par le visiteur. Sinon, elle peut rediriger à nouveau vers HTTPS, produire une adresse contenant le port interne d'une instance ou provoquer une boucle de redirection.

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

La prise en charge configurable des reverse proxys permet à RestFrontage de reconnaître cette information lorsqu'elle provient d'un proxy explicitement autorisé.

2. Périmètre et comportement par défaut

La fonctionnalité est désactivée par défaut. Sans section ReverseProxy, ou avec Enabled à false, aucun traitement supplémentaire n'est ajouté au pipeline de requêtes. L'intégration IIS déjà en place conserve son comportement.

Lorsqu'elle est activée, la fonctionnalité lit uniquement X-Forwarded-Proto pour déterminer si la requête d'origine utilise HTTP ou HTTPS. Ce traitement intervient avant HSTS, la redirection HTTPS et l'authentification.

Elle conserve les autres informations de la requête : nom d'hôte, adresse du correspondant, chemin et identité de l'utilisateur. Les en-têtes X-Forwarded-For, X-Forwarded-Host et X-Forwarded-Prefix ne sont pas activés par cette configuration.

3. Configurer les proxys de confiance

3.1 Prérequis

• Disposer d'une version de RestFrontage à jour pour la section ReverseProxy.
• Identifier l'adresse IP sous laquelle chaque proxy immédiat est vu par l'application.
• Disposer des droits nécessaires pour modifier la configuration de RestFrontage et celle du proxy.
• Prévoir le redémarrage de chaque instance concernée après modification.

3.2 Paramètres disponibles

Ajouter la section suivante à la racine du fichier appsettings.json de l'installation, en conservant les autres sections :

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

Paramètre	Valeur par défaut	Description
ReverseProxy:Enabled	false	Active la reconnaissance du protocole d'origine transmis par les proxys déclarés.
ReverseProxy:KnownProxies	Liste vide	Adresses IP exactes des proxys immédiats autorisés à transmettre cette information.

Lorsque Enabled vaut true, la liste doit contenir au moins une adresse IPv4 ou IPv6 valide. Les noms DNS, plages CIDR, jokers et adresses d'écoute génériques telles que 0.0.0.0 et :: ne sont pas acceptés.

Les adresses de boucle locale ne sont pas implicitement approuvées : ajouter explicitement 127.0.0.1 ou ::1 si elles sont utilisées. Les représentations IPv4 mappées en IPv6 sont également reconnues.

Une configuration activée comportant un paramètre inconnu, une liste vide ou une adresse invalide empêche le démarrage avec une erreur de configuration. Il n'existe pas de repli autorisant tous les proxys. Lorsque la fonctionnalité est désactivée, les paramètres inutilisés de cette section ne sont pas validés.

3.3 Proxy installé sur la même machine

Pour un proxy qui contacte RestFrontage par la boucle locale :

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

3.4 Proxy installé sur une autre machine

Pour un proxy dont l'adresse source vue par l'application est, par exemple, 10.20.0.10 :

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

En cas de plusieurs proxys pouvant contacter directement l'application, déclarer leurs adresses dans la même liste. Ne pas y placer les adresses des utilisateurs ni l'adresse publique du portail, sauf si cette dernière est réellement l'adresse source du proxy vue par RestFrontage.

3.5 Appliquer les changements

La configuration est lue au démarrage. Sous IIS, recycler le pool d'applications de chaque instance concernée après modification. Pour un autre mode d'hébergement, redémarrer le service qui héberge RestFrontage.

Les variables d'environnement peuvent également fournir ces valeurs :

Variable	Exemple de valeur
ReverseProxy__Enabled	true
ReverseProxy__KnownProxies__0	127.0.0.1
ReverseProxy__KnownProxies__1	::1

4. Préparer le routage du proxy

Le proxy doit transmettre le nom d'hôte public dans l'en-tête Host, car cette fonctionnalité ne récupère pas X-Forwarded-Host.

Pour une requête reçue en HTTPS, il doit définir X-Forwarded-Proto à https. Pour une requête publique reçue en HTTP, il doit soit rediriger le visiteur vers HTTPS, soit transmettre le protocole réel.

Limiter l'accès aux liaisons internes de RestFrontage aux composants prévus dans l'architecture. Lorsqu'un hôte partage le serveur avec le proxy, ses processus locaux peuvent eux aussi émettre des requêtes depuis la boucle locale : le serveur fait donc partie du périmètre de confiance.

4.1 Plusieurs relais ou intégration IIS existante

RestFrontage prend en compte uniquement la valeur la plus à droite de X-Forwarded-Proto, correspondant à l’information transmise par le proxy immédiat. Ce mécanisme ne reconstitue pas le parcours complet à travers plusieurs proxys et ne modifie pas les options de transfert d’en-têtes déjà utilisées par IIS

Avec IIS en hébergement hors processus, certains en-têtes peuvent déjà avoir été traités avant d'atteindre le pipeline de RestFrontage. Avec plusieurs relais, vérifier les informations réellement reçues par l'application avant de définir les adresses autorisées. Une liste de plusieurs proxys autorisés ne représente pas, à elle seule, la description d'une chaîne de relais.

5. Exemple avec IIS ARR et deux instances locales

Cet exemple illustre deux applications RestFrontage sur une même machine Windows. Chaque application utilise son propre pool IIS. Le site d'entrée ARR reçoit les utilisateurs sur une adresse HTTPS commune.

Élément	Valeur illustrative
Adresse publique	https://portail.example.com
Liaison du site ARR	HTTPS, port 443, certificat valide pour le nom public
Instance 1	HTTP, 127.0.0.1:18081
Instance 2	HTTP, 127.0.0.1:18082
Alias local de l'instance 1	application-noeud-1
Alias local de l'instance 2	application-noeud-2

5.1 Préparer les liaisons et les alias

1. Vérifier que les ports 18081 et 18082 sont disponibles.
2. Ajouter une liaison HTTP 127.0.0.1:18081 au premier site IIS, avec un nom d'hôte vide.
3. Ajouter une liaison HTTP 127.0.0.1:18082 au second site IIS, avec un nom d'hôte vide.
4. Conserver les éventuelles liaisons HTTPS utilisées pour les accès directs.
5. Ajouter les deux alias dans le fichier C:\Windows\System32\drivers\etc\hosts, depuis un éditeur exécuté en administrateur.

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

ARR utilise les noms des destinations pour distinguer les membres de la ferme. Deux alias permettent de représenter deux applications du même serveur sur des ports différents.

5.2 Configurer les instances et la ferme

1. Activer ReverseProxy sur les deux instances avec les adresses de boucle locale nécessaires.
2. Recycler les deux pools d'applications.
3. Dans ARR, ajouter application-noeud-1 à la ferme avec le port HTTP 18081.
4. Ajouter application-noeud-2 avec le port HTTP 18082.
5. Configurer le site d'entrée HTTPS pour conserver le nom d'hôte public et transmettre X-Forwarded-Proto: https vers les destinations HTTP.
6. Limiter la règle de routage au site d'entrée prévu pour cette application.

5.3 Particularités des tests multi-instance

Pour tester les caches mémoire, utiliser deux pools IIS distincts afin d'obtenir deux processus indépendants. Accéder aussi directement à chaque instance pour savoir précisément laquelle reçoit la lecture ou la modification.

Lorsque le scénario exige le passage d'une instance à l'autre derrière ARR, désactiver l'affinité client pendant le test. Désactiver également le cache ARR pour observer le cache applicatif. Ces réglages de test ne définissent pas automatiquement la configuration à retenir en production.

Le partage de l'authentification, des clés Data Protection, des sessions et des éventuels caches distribués relève de la configuration multi-instance de l'application. La section ReverseProxy ne réalise pas ce partage. Deux instances sur une seule machine restent indisponibles simultanément si cette machine s'arrête.

6. Vérifier le fonctionnement

Les commandes suivantes sont destinées à PowerShell sur la machine hébergeant l'exemple local. Elles affichent les en-têtes de réponse sans suivre les redirections.

6.1 Vérifier l'accès HTTP direct

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

Cette requête ne déclare pas de HTTPS d'origine. Si la redirection HTTPS et son port de destination sont configurés sur l'instance, la redirection doit rester active. L'activation de ReverseProxy ne doit pas, à elle seule, transformer cet accès HTTP en HTTPS.

6.2 Vérifier la reconnaissance du protocole d'origine

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/

Ces requêtes proviennent de la boucle locale explicitement autorisée. Elles doivent atteindre l'application sans redirection HTTP vers le port HTTPS interne d'une instance. Une redirection vers /Login ou /setup peut être normale selon l'état de l'installation.

6.3 Valider l'accès public

• Ouvrir l'adresse publique et vérifier son certificat HTTPS.
• Vérifier que les redirections conservent le nom public, sans alias ni port interne.
• Se connecter et parcourir les pages ainsi que les fonctions utilisées par les clients.
• Vérifier les cookies et la continuité de l'authentification selon la configuration multi-instance retenue.
• Vérifier dans les journaux ou les outils de supervision quelles instances reçoivent les requêtes.
• Pour les tests de cache, modifier un objet via une instance puis le relire via l'autre et observer la propagation attendue.

7. Diagnostiquer une configuration incorrecte

Symptôme	Vérifications
L'application ne démarre plus après activation	Vérifier la validité du JSON, les noms des paramètres et la présence d'au moins une adresse IP valide dans KnownProxies.
Une redirection vers un port interne persiste	Vérifier la version déployée, l'activation de la section, le recyclage du pool, l'en-tête transmis et l'adresse source du proxy vue par RestFrontage.
Une boucle de redirection apparaît	Vérifier le protocole déclaré par le proxy et la portée de la règle de routage, notamment sur les sites internes.
Une adresse interne apparaît dans une redirection	Vérifier que le proxy conserve le Host public. La section ReverseProxy ne traite pas X-Forwarded-Host.
Une erreur de certificat apparaît	Vérifier le nom couvert par le certificat de la liaison HTTPS concernée. La section ReverseProxy ne modifie pas la validation des certificats.
Les sessions se perdent lors du changement d'instance	Vérifier la configuration d'authentification, de protection des données et de stockage des sessions.
Une modification reste invisible sur une autre instance	Vérifier les caches applicatifs, l'invalidation distribuée, la propagation des événements et l'éventuel cache du proxy.

8. Revenir à la configuration précédente

Remettre ReverseProxy:Enabled à false, puis recycler les pools IIS ou redémarrer les services concernés.

Si le proxy transmet toujours les requêtes en HTTP, les applications peuvent de nouveau rediriger vers leurs ports HTTPS. Prévoir le routage correspondant avant de désactiver cette prise en charge sur une installation en service.

Références complémentaires

• ASP.NET Core derrière un proxy ou un répartiteur de charge
• Traitement des en-têtes provenant de proxys inconnus
• IIS ARR avec plusieurs applications sur une même machine