Merge pull request #3353 from joerg-richter-5234/#2975-Suggestion-Add-Permissions-Policy-as-configurable-option-to-SecureHeaders-GatewayFilter

Fixes gh-2975

Author: ryanjbaxter

docs/modules/ROOT/pages/spring-cloud-gateway-server-webflux/gatewayfilter-factories/secureheaders-factory.adoc

@@ -29,10 +29,87 @@ The following properties are available:
 To disable the default values set the `spring.cloud.gateway.filter.secure-headers.disable` property with comma-separated values.
 The following example shows how to do so:
 
-[source]
+.application.yml
+[source,yaml]
 ----
-spring.cloud.gateway.filter.secure-headers.disable=x-frame-options,strict-transport-security
+spring:
+  cloud:
+    gateway:
+      filter:
+        secure-headers:
+          disable: x-frame-options,strict-transport-security
 ----
 
-NOTE: The lowercase full name of the secure header needs to be used to disable it..
+To apply the `SecureHeaders` filter to a specific route, add the filter to the list of filters of that route.
+You can customize the route filter using arguments. Route configuration overrides the global default configuration for this route.
 
+.application.yml
+[source,yaml]
+----
+      - id: secureheaders_route
+        uri: http://example.org
+        predicates:
+        - Path=/**
+        filters:
+          - name: SecureHeaders
+            args:
+              disable: x-frame-options
+----
+
+NOTE: The lowercase full name of the secure header needs to be used to disable it.
+
+== Further options
+
+You may opt in to add the `Permissions-Policy` header to the response. Permissions Policy is a security header
+that allows web developers to manage which browser features a website can utilize. Please see
+https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy[Permissions-Policy] and
+https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#directives[Directives] to configure it
+for your environment.
+
+.application.yml
+[source,yaml]
+----
+spring:
+  cloud:
+    gateway:
+      filter:
+        secure-headers:
+          enable: permissions-policy
+          permissions-policy : geolocation=(self "https://example.com")
+----
+
+In the above https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/geolocation[example]
+the Geolocation API is disabled within all browsing contexts except for its own origin and those whose origin is "https://example.com".
+The Permissions-Policy may be configured separately for each route.
+
+.application.yml
+[source,yaml]
+----
+      - id: secureheaders_route
+        uri: http://anotherexample.org
+        predicates:
+        - Path=/**
+        filters:
+          - name: SecureHeaders
+            args:
+              disable: x-frame-options
+              enable: permissions-policy
+              permissions-policy : geolocation=("https://anotherexample.org")
+----
+
+WARNING: When you enable Permissions-Policy and do not explicitly configure any directives, a default value will be applied.
+Specifically, this default value disables a wide range of standardized and experimental features.
+This behavior might not be appropriate for your specific environment or use case.
+
+Permissions-Policy default value when enabled and no explicit configuration:
+
+`Permissions-Policy: accelerometer=(), ambient-light-sensor=(), autoplay=(), battery=(), camera=(), cross-origin-isolated=(),
+display-capture=(), document-domain=(), encrypted-media=(), execution-while-not-rendered=(), execution-while-out-of-viewport=(),
+fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), microphone=(), midi=(), navigation-override=(),
+payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), sync-xhr=(), usb=(),
+web-share=(), xr-spatial-tracking=()`
+
+
+NOTE: You can check the Permissions Policy feature list for Chrome with https://developer.chrome.com/docs/privacy-security/permissions-policy#chrome_devtools_integration[DevTool Integration].
+
+When you configure the header value for your environment, make sure to check the browser console for syntax errors.

spring-cloud-gateway-sample/src/main/resources/application-secureheaders.yml

@@ -0,0 +1,50 @@
+test:
+    hostport: httpbin.org:80
+  #  hostport: localhost:5000
+    uri: http://${test.hostport}
+  #uri: lb://httpbin
+
+
+spring:
+  cloud:
+    gateway:
+      filter:
+      default-filters:
+      #- PrefixPath=/httpbin
+      #- AddResponseHeader=X-Response-Default-Foo, Default-Bar
+
+      routes:
+      # =====================================
+      # to run server
+      # $ wscat --listen 9000
+      # to run client
+      # $ wscat --connect ws://localhost:8080/echo
+      - id: websocket_test
+        uri: ws://localhost:9000
+        order: 9000
+        predicates:
+        - Path=/echo
+      # =====================================
+      - id: default_path_to_httpbin_secureheaders
+        uri: ${test.uri}
+        order: 10000
+        predicates:
+        - Path=/**
+        filters:
+          - name: SecureHeaders
+            args:
+              disable: x-frame-options
+              enable: permissions-policy
+              permissions-policy : geolocation=("https://example.net")
+
+logging:
+  level:
+    org.springframework.cloud.gateway: TRACE
+    org.springframework.http.server.reactive: DEBUG
+    org.springframework.web.reactive: DEBUG
+    reactor.ipc.netty: DEBUG
+    reactor.netty: DEBUG
+
+management.endpoints.web.exposure.include: '*'
+
+