Merge pull request #2968 from AURIN/GEOS-8240-2

[GEOS-8240] Fix "Forwarded" header name, add user docs

doc/en/user/source/configuration/globalsettings.rst

@@ -61,7 +61,28 @@ Specifies the global character encoding that will be used in XML responses. Defa
 Proxy Base URL
 --------------
 
-GeoServer can have the capabilities documents report a proxy properly. The Proxy Base URL field is the base URL seen beyond a reverse proxy.
+GeoServer can have the capabilities documents report a proxy properly. "The Proxy Base URL" field is the base URL seen beyond a reverse proxy.
+
+Use headers for Proxy URL
+-------------------------
+
+Checking this box allows a by-request modification of the proxy URL using templates (templates based on HTTP proxy headers).
+The supported proxy headers are:
+#. **X-Forwarded-Proto** The protocol used by the request
+#. **X-Forwarded-Host** The hostname and port of the proxy URL
+#. **X-Forwarded-For** The client IP address
+#. **X-Forwarded-Path** The path of the proxy URL (this is not an official HTTP header, although it is supported by some web-servers)
+#. **Forwarded** Header that supersedes the "X-Forwarded-*" headers above. It has these components: "by", "for", "host", "proto", "path" (this component is not official, but added for consistency with ``X-Forwarded-Path``)
+#. **Host** Same as ``X-Forwarded
+
+For instance, to allow different protocols (``http`` and ``https``) and different hostnames, the proxy base URL field may be changed to: ``${X-Forwarded-Proto}://${X-Forwarded-Host}/geoserver``
+The use of the ``Forwarded`` header is a tad more complex, as its components have to be referenced in templates with the dot-notation, as in: ``{Forwarded.proto}://${Forwarded.host}/geoserver``.
+
+Multiple templates can be put into the "Proxy Base URL". These templates provide fall-backs, since only the first one that is fully matched is used. 
+For instance, a Proxy Base URL of ``http://${X-Forwarded-Host}/geoserver http://www.foo.org/geoserver`` (Templates are space-separated.) can result in either: ``http://www.example.com/geoserver`` (if ``X-Forwarded-Host`` is set to ``www.example.com``.)  or ``http://www.foo.org/geoserver``  (if ``X-Forwarded-Host`` is not set.)
+
+Header names in templates are case-insentive.
+
 
 Logging Profile
 ---------------

src/main/src/main/java/org/geoserver/config/impl/GeoServerInfoImpl.java

@@ -222,7 +222,7 @@ public void setGlobalServices(Boolean forceVirtualServices) {
     }
 
     public Boolean isUseHeadersProxyURL() {
-        return useHeadersProxyURL;
+        return useHeadersProxyURL == null ? false : useHeadersProxyURL;
     }
 
     public void setUseHeadersProxyURL(Boolean useHeadersProxyURL) {

src/main/src/main/java/org/geoserver/ows/ProxifyingURLMangler.java

@@ -17,7 +17,7 @@
 public class ProxifyingURLMangler implements URLMangler {
 
     public enum Headers {
-        FORWARDED("X-Forwarded"),
+        FORWARDED("Forwarded"),
         FORWARDED_PROTO("X-Forwarded-Proto"),
         FORWARDED_HOST("X-Forwarded-Host"),
         FORWARDED_PATH("X-Forwarded-Path"),
@@ -169,7 +169,7 @@ private Map<String, String> compileHeadersMap() {
                                                             String.format(
                                                                     "%s%s%s",
                                                                     TEMPLATE_PREFIX,
-                                                                    Headers.FORWARDED.toString()
+                                                                    Headers.FORWARDED.asString()
                                                                             + "."
                                                                             + comp,
                                                                     TEMPLATE_POSTFIX),

src/main/src/main/java/org/geoserver/ows/QuickTemplate.java

@@ -16,7 +16,8 @@
 class QuickTemplate {
 
     /**
-     * Simple replacement of a set of variables in a string with their values
+     * Simple replacement of a set of variables in a string with their values. The variable names to
+     * expand are case-insensitive.
      *
      * @param template
      * @param variables

src/main/src/test/java/org/vfny/geoserver/util/URLProxifyingTest.java

@@ -71,7 +71,7 @@ public String getHeader(String name) {
                         new GeoServerInfoImpl() {
                             @Override
                             public Boolean isUseHeadersProxyURL() {
-                                return useHeadersProxyURLIn;
+                                return useHeadersProxyURLIn == null ? false : useHeadersProxyURLIn;
                             }
                         })
                 .anyTimes();
@@ -99,6 +99,18 @@ public void clearAppContext() {
         GeoServerExtensionsHelper.init(null);
     }
 
+    @Test
+    public void testNullFlag() throws Exception {
+        createAppContext(null, null, null, null, null, null, null, null);
+        StringBuilder baseURL = new StringBuilder();
+        this.mangler.mangleURL(
+                baseURL,
+                new StringBuilder(),
+                new HashMap<String, String>(),
+                URLMangler.URLType.SERVICE);
+        assertEquals("", baseURL.toString());
+    }
+
     @Test
     public void testNoProxyBaseURL() throws Exception {
         createAppContext(null, false, null, null, null, null, null, null);