Configure multiple instances of RestFrontage behind IIS ARR

• Undefined type

This guide describes how to configure IIS ARR to distribute requests across multiple instances of RestFrontage and pass the original HTTPS to them. The example uses two instances on a single machine; the principle extends to more instances, hosted on one or more machines. Each instance must allow the proxy address as it sees it

This documentation is intended for integrators and administrators who deploy Immersive RestFrontage behind a reverse proxy. It describes how to recognize the original HTTPS protocol, how to configure trusted proxies, and what checks should be performed before provisioning.

Names portail.example.com, application-noeud-1 and application-noeud-2, and the addresses and ports in the examples, are illustrative. Replace them with the values for your installation.

1. Understanding the role of the reverse proxy

A reverse proxy receives requests from users and then forwards them to RestFrontage. This includes HTTPS input, routing to applications, and distributing requests across multiple instances.

When the proxy receives a request over HTTPS and forwards it to RestFrontage over HTTP, the application must know the protocol used by the visitor. Otherwise, it can redirect back to HTTPS, produce an address containing the inner port of an instance, or cause a redirect loop.

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

Configurable reverse proxy support allows RestFrontage to recognize this information when it comes from an explicitly authorized proxy.

2. Default scope and behavior

The functionality is disabled by default. Without section ReverseProxy, or with Enabled à false, no additional processing is added to the query pipeline. The IIS integration that is already in place retains its behavior.

When enabled, the feature reads only X-Forwarded-Proto to determine whether the original request uses HTTP or HTTPS. This processing occurs before HSTS, HTTPS redirection, and authentication.

It preserves the other information in the request: hostname, caller address, path, and user identity. Headers X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Prefix are not enabled by this configuration.

3. Configure Trusted Proxies

3.1 Prerequisites

• Have an up-to-date version of RestFrontage for the ReverseProxy.
• Identify the IP address under which each immediate proxy is viewed by the application.
• Have the necessary rights to change the configuration of RestFrontage and the proxy.
• Schedule the restart of each affected instance after modification.

3.2 Available Settings

Add the next section to the root of the file appsettings.json of the installation, keeping the other sections:

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

Parameter	Default	Description
ReverseProxy:Enabled	false	Enables recognition of the origin protocol transmitted by declared proxies.
ReverseProxy:KnownProxies	Empty list	Exact IP addresses of the immediate proxies authorized to transmit this information.

When Enabled is worth true, the list must contain at least one valid IPv4 or IPv6 address. DNS names, CIDR ranges, wildcards, and generic listeners such as 0.0.0.0 and :: are not accepted.

Local loop addresses are not implicitly trusted: explicitly add 127.0.0.1 or ::1 if used. IPv4 representations mapped to IPv6 are also recognized.

An enabled configuration with an unknown setting, an empty list, or an invalid address prevents booting with a configuration error. There is no fallback that allows all proxies. When the feature is disabled, the unused settings in this section are not validated.

3.3 Proxy installed on the same machine

For a proxy that contacts RestFrontage through the local loop:

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

3.4 Proxy installed on another machine

For a proxy whose source address seen by the application is, for example, 10.20.0.10 :

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

If there are multiple proxies that can contact the application directly, declare their addresses in the same list. Do not include user addresses or the portal's public address unless the public address of the portal is actually the source address of the proxy as seen by RestFrontage.

3.5 Enforce changes

The configuration is read at startup. Under IIS, recycle the application pool of each affected instance after modification. For a different hosting mode, restart the service that hosts RestFrontage.

Environment variables can also provide these values:

Variable	Example value
ReverseProxy__Enabled	true
ReverseProxy__KnownProxies__0	127.0.0.1
ReverseProxy__KnownProxies__1	::1

4. Prepare Proxy Routing

The proxy must pass the public hostname in the header Host, because this feature does not recover X-Forwarded-Host.

For a request received over HTTPS, it must set X-Forwarded-Proto à https. For a public request received over HTTP, it must either redirect the visitor to HTTPS or pass the actual protocol.

Limit access to RestFrontage's internal bindings to the components provided for in the architecture. When a host shares the server with the proxy, its local processes can also make requests from the local loop, so the server is part of the trusted perimeter.

4.1 Multiple relays or existing IIS integration

RestFrontage only considers the rightmost value of X-Forwarded-Proto, corresponding to the information transmitted by the immediate proxy. This mechanism does not reconstruct the entire path through multiple proxies or change the header forwarding options already used by IIS

With IIS hosted out of process, some headers may have already been processed before reaching the RestFrontage pipeline. With multiple relays, verify the information actually received by the application before defining the allowed addresses. A list of multiple allowed proxies does not, on its own, represent the description of a relay chain.

5. Example with IIS ARR and two local instances

This example shows two RestFrontage applications on a single Windows machine. Each application uses its own IIS pool. The ARR ingress site receives users on a common HTTPS address.

Element	Illustrative value
Public address	https://portail.example.com
ARR Site Binding	HTTPS port 443, certificate valid for the public name
Instance 1	HTTP, 127.0.0.1:18081
Instance 2	HTTP, 127.0.0.1:18082
Local alias of instance 1	application-noeud-1
Local alias of instance 2	application-noeud-2

5.1 Prepare bindings and aliases

1. Verify that the ports 18081 and 18082 are available.
2. Add an HTTP binding 127.0.0.1:18081 to the first IIS site, with an empty hostname.
3. Add an HTTP binding 127.0.0.1:18082 at the second IIS site, with an empty hostname.
4. Keep any HTTPS links used for direct access.
5. Add both aliases to the C:\Windows\System32\drivers\etc\hosts, from an editor running as an administrator.

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

ARR uses the names of the destinations to distinguish the members of the farm. Two aliases are used to represent two applications on the same server on different ports.

5.2 Configure instances and farm

1. Activate ReverseProxy on both instances with the necessary local loop addresses.
2. Recycle both application pools.
3. In ARR, add application-noeud-1 on the farm with the HTTP port 18081.
4. Add to cart application-noeud-2 with HTTP port 18082.
5. Configure the HTTPS ingress site to keep the public hostname and pass X-Forwarded-Proto: https to HTTP destinations.
6. Limit the routing rule to the intended ingress site for this application.

5.3 Particularities of multi-instance testing

To test memory caches, use two separate IIS pools to obtain two independent processes. Also go directly to each instance to know precisely which one is receiving the read or modification.

When the scenario requires switching from one instance to another behind ARR, disable client affinity during testing. Also disable ARR cache to observe the application cache. These test settings do not automatically define the configuration to be retained in production.

Sharing authentication, Data Protection keys, sessions, and any distributed caches is part of the application's multi-instance configuration. The ReverseProxy does not perform this sharing. Two instances on a single machine remain unavailable simultaneously if that machine shuts down.

6. Check operation

The following commands are for PowerShell on the machine hosting the on-premises sample. They display the response headers without following the redirects.

6.1 Check HTTP Direct Access

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

This request does not declare an original HTTPS. If HTTPS redirection and its destination port are configured on the instance, the redirect must remain active. Enabling ReverseProxy should not, on its own, transform this HTTP access into HTTPS.

6.2 Verify the recognition of the original protocol

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/

These requests come from the explicitly allowed local loop. They must reach the application without an HTTP redirect to an instance's internal HTTPS port. A redirect to /Login or /setup may be normal depending on the condition of the installation.

6.3 Validate public access

• Open the public address and verify its HTTPS certificate.
• Verify that redirects retain the public name, without aliases or internal ports.
• Log in and browse the pages and functions used by customers.
• Verify cookies and authentication continuity according to the chosen multi-instance configuration.
• Check in the logs or monitoring tools which instances are receiving the requests.
• For cache tests, modify an object through one instance and then replay it through the other and observe the expected propagation.

7. Diagnosing an incorrect configuration

Symptom	Audits
The app no longer starts after activation	Check the validity of the JSON, parameter names, and the presence of at least one valid IP address in KnownProxies.
A redirect to an internal port persists	Verify the deployed version, section activation, pool recycle, transmitted header, and proxy source address seen by RestFrontage.
A redirect loop appears	Check the protocol declared by the proxy and the scope of the routing rule, especially on internal sites.
An internal address appears in a redirect	Verify that the proxy maintains the Host public. The ReverseProxy does not treat X-Forwarded-Host.
A certificate error appears	Check the name covered by the certificate of the HTTPS link in question. The ReverseProxy does not change certificate validation.
Sessions are lost when switching instances	Verify the authentication, data protection, and session storage configuration.
A change remains invisible on another instance	Check application caches, distributed invalidation, event propagation, and any proxy cache.

8. Revert to previous configuration

Hand over ReverseProxy:Enabled à false, and then recycle the IIS pools or restart the affected services.

If the proxy is still forwarding requests over HTTP, applications can redirect to their HTTPS ports. Plan for the corresponding routing before disabling this support on a live installation.

Additional References

• ASP.NET Core behind a proxy or load balancer
• Processing Headers from Unknown Proxies
• IIS ARR with multiple applications on one machine