Hosting the Portal behind an IIS Reverse Proxy
By default the Hopp Portal runs as a Windows Service and terminates HTTPS itself, as described in Setting up the Master Server. This article covers the other layout the Portal supports: the Windows Service stays, and IIS sits in front of it as a reverse proxy. IIS holds the certificate, terminates HTTPS and forwards each request over plain HTTP to the Portal on the same machine.
Pick this layout when:
- IIS is already the HTTPS front door on the Master Server;
- the Portal should share a hostname with other sites; or
- the Portal should live on a sub-path, such as
https://your-server/portal.
This is not running the Portal inside IIS through the ASP.NET Core Module, where IIS hosts the Portal process itself and there is no Windows Service.
How the pieces fit together
- The Portal listens on an internal HTTP port, for instance
5080, and opens no HTTPS port. Only the proxy should be able to reach that port. - An IIS site with an HTTPS binding forwards every request to that port with a URL
Rewrite rule, setting the
X-Forwarded-For,X-Forwarded-ProtoandX-Forwarded-Hostheaders. - The Portal trusts those headers only from the proxies you list. With IIS on the
same machine, that is the single address
127.0.0.1. - The Portal URL on the wizard's Connectivity page is the address people type into the browser: the IIS site's address, not the internal port.
The steps assume a Master Server with the Portal already installed and configured.
Step 1: Switch the Portal to reverse-proxy mode
Open the configuration wizard's HTTPS & reverse proxy page:
- New installation: you reach it on your first walk through the wizard.
- Existing installation: sign in as an administrator, choose Reconfigure under
System settings, and restart the service. It comes back in setup mode, which listens
only on
http://localhost:5000: open the wizard there, on the server itself (not through the IIS address), and walk to the same page.
Pick Yes, reverse proxy and fill in the fields.
| Field | Value | Notes |
|---|---|---|
| Internal HTTP port | 5080 | Any free port. IIS forwards to it. |
| Known proxies | 127.0.0.1 | The address IIS connects from. IP addresses or CIDR ranges only, not a hostname. |
| Sub-path | empty | Empty hosts at the root; see Hosting on a sub-path. |
| Forwarded headers | XForwardedFor,XForwardedProto,XForwardedHost | The default; with a Sub-path the wizard adds XForwardedPrefix. Leave what it fills in. |
Apply the wizard and restart the Hopp Portal service. It now listens on the internal
port over plain HTTP; its former HTTPS port is closed, so the old address stops
answering until IIS is in place.
The wizard writes the settings to %ProgramData%\HoppTech\Portal\appsettings.portal.json:
"Hosting": {
"ReverseProxy": {
"Enabled": true,
"InternalHttpUrl": "http://+:5080",
"KnownProxies": [ "127.0.0.1" ],
"KnownNetworks": [],
"ForwardedHeaders": "XForwardedFor,XForwardedProto,XForwardedHost"
}
}
The + binds the internal listener on every network interface. To restrict it:
- With IIS on the same machine, you can edit
InternalHttpUrltohttp://127.0.0.1:5080, so only the machine itself can connect. - Otherwise, block the port in the Windows firewall for everything except the proxy.
With both KnownProxies and KnownNetworks empty, the Portal refuses to start in
reverse-proxy mode. It returns to setup mode and gives the reason on the wizard's
Welcome page and in its log under %ProgramData%\HoppTech\Portal\logs. Always list the
proxy's address.
Step 2: Prepare IIS
These steps assume the IIS Web Server role is installed. Each is done once per server.
Install the features and add-ons
- WebSocket Protocol (a Web Server feature, under Application Development). The Portal pushes notifications and live status over WebSockets, and IIS only forwards them with this feature on. Without it, updates can arrive late or not at all.
- URL Rewrite Module 2.1, a Microsoft add-on from the IIS site. Install it before ARR.
- Application Request Routing 3.0 (ARR), from the same place. It depends on URL Rewrite.
Both add-ons are MSI packages; silent install:
msiexec /i <package>.msi /quiet /norestart.
Change two ARR proxy settings
| Setting | Default | Set to |
|---|---|---|
| Enable proxy | off | ticked |
| Reverse rewrite host in response headers | on | cleared |
In IIS Manager, select the server node, open Application Request Routing Cache, choose Server Proxy Settings on the right, change both and apply. From PowerShell:
Import-Module WebAdministration
Set-WebConfigurationProperty -PSPath 'MACHINE/WEBROOT/APPHOST' `
-Filter 'system.webServer/proxy' -Name 'enabled' -Value 'True'
Set-WebConfigurationProperty -PSPath 'MACHINE/WEBROOT/APPHOST' -Filter 'system.webServer/proxy' -Name 'reverseRewriteHostInResponseHeaders' -Value 'False'
With the rewriting left on, ARR changes the Portal's redirect to an external identity provider so that it points at the IIS site instead, and sign-in through that provider never completes. Both settings apply to the whole server, so they also change any other site that ARR proxies on it.
Allow the forwarded headers
IIS lets a rewrite rule set only server variables on its server-wide allow list. In IIS
Manager, select the server node, open URL Rewrite,
choose View Server Variables and add HTTP_X_FORWARDED_FOR,
HTTP_X_FORWARDED_PROTO, HTTP_X_FORWARDED_HOST and HTTP_X_FORWARDED_PREFIX (the
last only for the sub-path rule). From PowerShell:
Import-Module WebAdministration
foreach ($name in 'HTTP_X_FORWARDED_FOR', 'HTTP_X_FORWARDED_PROTO', 'HTTP_X_FORWARDED_HOST', 'HTTP_X_FORWARDED_PREFIX') {
Add-WebConfigurationProperty -PSPath 'MACHINE/WEBROOT/APPHOST' `
-Filter 'system.webServer/rewrite/allowedServerVariables' -Name '.' -Value @{ name = $name }
}
Step 3: Create the IIS site that forwards to the Portal
- Create an empty folder for the site, for instance
C:\inetpub\hopp-portal. It only holds theweb.configbelow; the site serves no files of its own. - In IIS Manager, add a website on that folder with an https binding on port 443 (or the port in your Portal URL) and the certificate your users should see. Add no http binding. IIS serves HTTP/2 on an https binding by default, so the HTTP/2 advice in Setting up the Master Server needs no step here, unless Disable HTTP/2 is ticked on the binding.
- Save the following as
web.configin the site folder.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="PortalReverseProxy" stopProcessing="true">
<match url="(.*)" />
<serverVariables>
<set name="HTTP_X_FORWARDED_FOR" value="{REMOTE_ADDR}" />
<set name="HTTP_X_FORWARDED_PROTO" value="https" />
<set name="HTTP_X_FORWARDED_HOST" value="{HTTP_HOST}" />
</serverVariables>
<action type="Rewrite" url="http://127.0.0.1:5080/{R:1}" />
</rule>
</rules>
</rewrite>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="104857600" />
</requestFiltering>
</security>
</system.webServer>
</configuration>
Two details in this rule matter:
- Forward to
127.0.0.1, notlocalhost.localhostcan resolve to the IPv6 loopback::1, but the internal listener accepts IPv4 only, and the Portal trusts forwarded headers only from the addresses in Known proxies. Use the IPv4 literal on both sides. X-Forwarded-Protois fixed tohttpsbecause the site has only an HTTPS binding. If you keep an http binding on the same site, redirect it to https rather than letting it reach this rule.
The requestLimits element raises the largest request body IIS accepts from its default
of 30,000,000 bytes to 104,857,600 bytes, the Portal's default of 100 MB. IIS checks a
request against its own limits before it forwards it, so they must allow what the Portal
is configured to accept. If you raise the limits on the wizard's
Request Limits page, raise
them here to match: raising them in the wizard alone does not help when IIS rejects the
request first, with a 404.13 error for a body that is too large.
Browse to the Portal URL from another machine. You should land on the Portal sign-in
page, and the address bar should stay on https://.
With an external identity provider, signing out returns through
/signout-callback-oidc with a query string near the IIS default limit of 2,048
characters (maxQueryString): 1,850 to 1,890 characters for a 22-character Portal URL.
The Portal URL appears in it more than once, encoded, so each extra character adds
about three, and a Portal URL a few dozen characters longer can go over. IIS then
answers with a 404.15 error page: the user is signed out but does not get back to the
Portal. With a long Portal URL, raise the limit in the site's web.config, on the
requestLimits element:
<requestLimits maxAllowedContentLength="104857600" maxQueryString="4096" />
Hosting on a sub-path
To host the Portal at https://your-server/portal instead of the root, three settings
must agree:
| Where | Set | Why |
|---|---|---|
| Wizard, HTTPS & reverse proxy page | Sub-path /portal | Writes Hosting:ReverseProxy:BasePath; the Portal builds every link and redirect under that prefix. |
| Wizard, Connectivity page | Portal URL https://your-server/portal | The Portal builds its sign-in callback address from it. |
The site's web.config | the rule below, in place of the root rule | It keeps the prefix; see Do not strip the prefix below. |
<rule name="PortalUnderSubPath" stopProcessing="true">
<match url="^portal(/.*)?$" />
<serverVariables>
<set name="HTTP_X_FORWARDED_FOR" value="{REMOTE_ADDR}" />
<set name="HTTP_X_FORWARDED_PROTO" value="https" />
<set name="HTTP_X_FORWARDED_HOST" value="{HTTP_HOST}" />
<set name="HTTP_X_FORWARDED_PREFIX" value="" />
</serverVariables>
<action type="Rewrite" url="http://127.0.0.1:5080/portal{R:1}" />
</rule>
The empty HTTP_X_FORWARDED_PREFIX removes any X-Forwarded-Prefix header the client
sent. IIS would pass it on unchanged, and the Portal trusts it because it comes from a
known proxy, so without this line a client can steer the Portal's links and redirects,
even to another host.
A rule that forwards /portal/x as /x (an action of http://127.0.0.1:5080/{R:1})
without an X-Forwarded-Prefix header means the Portal never sees /portal: every
link and redirect it produces, the sign-in page included, escapes the sub-path, and
nothing reports an error.
Checking that the proxy is trusted
When the Portal trusts the proxy, it sees each request as HTTPS and adds the
Strict-Transport-Security header to its responses. Look for that header in the
browser's developer tools, on the sign-in page, using the server's real hostname:
ASP.NET Core never sends it to localhost or 127.0.0.1, so a test against those
looks like a failure even when everything is correct.
If the header is missing, the forwarded headers are not being honoured: check that the
rule forwards to 127.0.0.1 and that the same address is in Known proxies.
Related
- Setting up the Master Server: the wizard walk, and the Reconfigure route for changing an existing installation.
- Running the Portal inside IIS through the ASP.NET Core Module, with no Windows Service, is covered in a separate article, Hosting the Portal under IIS.