proxy: add per-route request headers setting (#346)

Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>

docs/docs/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### New
 
+- Allow setting request headers for back-end requests on per route basis in policy. [GH-308]
 - Add endpoint to support "forward-auth" integration with third-party ingresses and proxies. Supports [nginx]https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/, [nginx-ingress](https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/), and [Traefik](https://docs.traefik.io/middlewares/forwardauth/). [GH-324]
 - Add insecure transport support. [GH-328]
 - Add setting to override HTTPS backend's TLS Server Name. [GH-297]
@@ -13,7 +14,7 @@
 ### Security
 
 - The user's original intended location before completing the authentication process is now encrypted and kept confidential from the identity provider. [GH-316]
-- Under certain circumstances, where debug logging was enabled, pomerium's shared secret could be leaked to http access logs as a query param.
+- Under certain circumstances, where debug logging was enabled, pomerium's shared secret could be leaked to http access logs as a query param. [GH-338]
 
 ### Fixed
 
@@ -288,3 +289,4 @@
 [gh-319]: https://github.com/pomerium/pomerium/issues/319
 [gh-328]: https://github.com/pomerium/pomerium/issues/328
 [gh-332]: https://github.com/pomerium/pomerium/pull/332/
+[gh-338]: https://github.com/pomerium/pomerium/issues/338

docs/docs/reference/reference.md

@@ -491,6 +491,28 @@ Note: This setting will replace (not append) the system's trust store for a give
 
 Pomerium supports client certificates which can be used to enforce [mutually authenticated and encrypted TLS connections](https://en.wikipedia.org/wiki/Mutual_authentication) (mTLS). For more details, see our [mTLS example repository](https://github.com/pomerium/examples/tree/master/mutual-tls) and the [certificate docs](./certificates.md).
 
+### Set Request Headers
+
+- Config File Key: `set_request_headers`
+- Type: map of `strings` key value pairs
+- Optional
+
+Set Request Headers allows you to set static values for given request headers. This can be useful if you want to pass along additional information to downstream applications as headers, or set authentication header to the request. For example:
+
+```yaml
+- from: https://httpbin.corp.example.com
+  to: https://httpbin.org
+  allowed_users:
+    - bdd@pomerium.io
+    - bobbydesimone@gmail.com
+    - bobby@tdia.com
+  set_request_headers:
+    # works auto-magically!
+    # https://httpbin.corp.example.com/basic-auth/root/hunter42
+    Authorization: Basic cm9vdDpodW50ZXI0Mg==
+    X-Your-favorite-authenticating-Proxy: "Pomerium"
+```
+
 # Authenticate Service
 
 ## Authenticate Service URL