Run the service behind IIS or a proxy

If there's an IIS, a load balancer, or another proxy in front of the service, by default the service sees only the proxy's address. For origin rules, the sign-in policy, and the HTTPS requirement to work correctly, the service has to trust the proxy explicitly.

The proxy reports the caller's address in X-Forwarded-For, the scheme in X-Forwarded-Proto, and the host the caller addressed in X-Forwarded-Host. The service believes these headers only if they come from an address under Gateway:Security:TrustedProxies. Without this entry, it would see every caller with the proxy's address—if the proxy is in the corporate network, everyone would count as „inside“.

1. Have the service listen only on 127.0.0.1 (or on an address only the proxy reaches), for example with Kestrel:Endpoints:Http:Url = http://127.0.0.1:8434.

2. Register the proxy as trusted:

   "Security": { "TrustedProxies": [ "127.0.0.1", "::1" ] }

3. Have the proxy set X-Forwarded-For, X-Forwarded-Proto: https, and X-Forwarded-Host. If X-Forwarded-For is missing, every request counts as coming from the proxy itself—with IIS on the same computer, that means 127.0.0.1: inside, protected, exempt from every network rule. So after setup, check in the audit that the real origins appear there. The service builds the absolute addresses in its responses from scheme and host: the service document and next pages of the OData interface, Location after a create, and the one-time links of the administration API. Without X-Forwarded-Host, they point to 127.0.0.1 and can't be reached from outside. Of each header, the service takes the last entry, the one the nearest proxy appended, and of the host only a host name or address with a port.

4. With IIS: the installation package with GW_MODE=iis takes care of steps 1 and 2 and writes a template iis\web.config to the program folder. It redirects http to https, forwards every request to http://127.0.0.1:<GW_PORT>, sets X-Forwarded-Proto: https and X-Forwarded-Host, and allows addresses of up to 8,192 characters. Use it to create an IIS website with your certificate. The template needs the IIS modules URL Rewrite and Application Request Routing. In IIS Manager, under URL Rewrite > View Server Variables, allow the variables HTTP_X_FORWARDED_PROTO and HTTP_X_FORWARDED_HOST; without this permission, IIS rejects the rule that sets the headers and responds with 500.

   

   The template's rules under URL Rewrite (German-language IIS Manager).

   

   The two allowed server variables.

Result: the audit names the caller's address, not the proxy's; a request over https at the proxy counts as a protected connection, and the addresses in responses name the proxy with https.

• Windows sign-in only without shared connections. Windows sign-in applies to the connection on which it happened. A proxy that routes requests from different users over one connection to the service would give the second user the rights of the first. IIS with Application Request Routing forwards requests over shared connections. That's why setup-host --mode iis sets AuthMode to PersonalKey, without Windows sign-in; people sign in with their personal key. If Windows is in AuthMode anyway and a trusted proxy is entered, the service logs a warning at startup.
• Reading the origin: the service reads X-Forwarded-For from the nearest hop; the first address that isn't itself a trusted proxy applies. An entry the client adds at the front itself is thus not counted. An unreadable value makes the origin unknown; an unknown origin doesn't lift any block.
• Server header: the service itself doesn't name its server software. Behind IIS, IIS adds Server: Microsoft-IIS/10.0. On IIS 10 and later, removeServerHeader="true" on the template's requestFiltering element removes it: <requestFiltering removeServerHeader="true">. Earlier IIS versions don't know the attribute and answer with error 500.19, so the template doesn't set it.
• Long addresses: without the template, IIS and http.sys allow only 2 KB of query string; clients can send long conditions in the body anyway, see HTTP: long queries.

• Configuration: TrustedProxies
• Installation package: properties
• Set up HTTPS and the certificate