Foswiki behind reverse proxies

When Foswiki is installed behind a reverse proxy, some critical information is unavailable during the bootstrap process. This can cause challenges getting a valid initial configuration out of the bootstrap process:

1. The protocol used to connect from the client to the server will be hidden. The client may use SSL (https://) connections, but the bootstrap will see http:// on port 80, and will use the wrong protocol for the {DefaultUrlHost} setting.
2. The hostname in use may also be hidden. Foswiki will detect the hostname or IP used by the proxy to reach Foswiki rather than the hostname the user is using.
3. Non-standard ports may also be incorrectly detected.

Some of these issues can be mitigated by correctly setting the X-Forwarded-* headers on the proxy server. Some will require fixes in an upcoming Foswiki release.

Proxies and Foswiki 2.1.4

• Foswiki will detect the X-Forwarded-Host header and will set the {DefaultUrlHost} from this header. It only will work when a single proxy is in-line Multiple proxy hops will break the configuration.
• If SSL is terminated at the proxy, Foswiki will not detect https:// for the protocol. Override this by adding "?SSL=1" to the initial connection: https://mynewsite.com/Main/WebHome?SSL=1
• Foswiki will not log the real client IP. All Foswiki event logs will show the Proxy Server's IP as the client IP.
• IP Address Matching for sessions must be disabled. {Sessions}{UseIPMatching} (Default is enabled on Foswiki 2.x)

Best current configuration options for Foswiki 2.1.4:

• Set the {DefaultUrlHost} to the protocol://hostname used by users to contact the proxy.
• Set {ForceDefaultUrlHost} to 1
• Set {Sessions}{UseIPMatching} to 0

Foswiki 2.1.5

• Foswiki will detect the X-Forwarded-Host header, and split it so that multiple hop proxies are supported.
• Configuration recommendations are unchanged.

Plans for 2.2

When bootstrap detects a Proxy, it will set the ForceDefaultHostUrl and set the DefaultUrlHost to the detected first-hop proxy name. This is the safest configuration with an unknown proxy. However it is not flexible, and will not support multiple proxy hosts, and will not support local users inside the proxy.

Foswiki will have a configuration option to honor the X-Forwarded-* headers.

• X-Forwarded-For Identifies the client IP, overrides REMOTE_ADDRESS variable. This should allow IP Matching to work, and will log the correct IP of the actual client.

The next 3 headers will be used to establish the URL used by the user to access Foswiki.

• X-Forwarded-Host Captures the hostname used by the client in it's initial request.
• X-Forwarded-Proto Specifies if the client used an HTTP or HTTPS secure connection.
• X-Forwarded-Port Specifies the original port used by the client.

Note that not all proxy servers return all 4 headers. This is dependent upon the configuration of the proxy server. Apache does not return the protocol or the port by default. They must be set using:

RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"

None of the X-Forwarded headers are RFC standards. However they are all defacto standards and widely used. There is a new Standards Track header for proxies defined in RFC:7239

• Forwarded: New standards based header replaces the X-Forwarded* headers.

It has not been determined if this new header will be supported in Foswiki.