docs: traefik + oathkeeper (#577)

This PR contains the documentation for the updates done in ory/oathkeeper#904.

docs/oathkeeper/guides/traefik-proxy-integration.md

@@ -0,0 +1,38 @@
+---
+id: traefik-proxy-integration
+title: Traefik Proxy Integration
+---
+
+[Traefik Proxy](https://doc.traefik.io/traefik/) is modern HTTP proxy and load
+balancer for microservices, oathkeeper can be integrated with via the
+[ForwardAuth Middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/)
+by making use of the available
+[Access Control Decision API](index.md#access-control-decision-api).
+
+To achieve this,
+
+- configure traefik
+  - to make use of the aforesaid ForwardAuth middleware by setting the `address`
+    property to the decision URL endpoint and
+  - by including the required header name(s), the oathkeeper sets in the HTTP
+    responses into the `authResponseHeaders` property.
+- configure the route of your service to make use of this middleware
+
+Example (using Docker labels):
+
+```.yaml
+edge-router:
+  image: traefik
+  # further configuration
+  labels:
+    - traefik.http.middlewares.oathkeeper.forwardauth.address=http://oathkeeper:4456/decisions
+    - traefik.http.middlewares.oathkeeper.forwardauth.authResponseHeaders=X-Id-Token,Authorization
+    # further labels
+
+service:
+  image: my-service
+  # further configuration
+  labels:
+    - traefik.http.routers.service.middlewares=oathkeeper
+    # further labels
+```

docs/oathkeeper/index.md

@@ -186,10 +186,13 @@ X-User-ID: john.doe
 The decision engine allows to configure how ORY Oathkeeper authorizes HTTP
 requests. Authorization happens in four steps, each of which can be configured:
 
-1. **Access Rule Matching:** Verifies that the HTTP method, path, and host of
-   the incoming HTTP request conform to your access rules. The request is denied
-   if no access rules match. The configuration of the matching access rule
-   becomes the input for the next steps.
+1. **Access Rule Matching:** Verifies that the HTTP method, path, scheme, and
+   host of the incoming HTTP request conform to your access rules. The
+   information is taken either from the URL, or from the `X-Forwarded-Method`,
+   `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Uri` headers (if
+   present) of the incoming request. The request is denied if no access rules
+   match. The configuration of the matching access rule becomes the input for
+   the next steps.
 2. **Authentication:** Oathkeeper can validate credentials via a variety of
    methods like Bearer Token, Basic Authorization, or cookie. Invalid
    credentials result in denial of the request. The "internal" session state

docs/oathkeeper/pipeline/error.md

@@ -415,7 +415,10 @@ conditions under the `when` key.
 
 If you want to append the current url (where the error happened) to address
 redirected to, You can specify `return_to_query_param` to set the name of
-parameter that will hold the url.
+parameter that will hold the url. The information about the current url is taken
+either from the URL, or from the `X-Forwarded-Method`, `X-Forwarded-Proto`,
+`X-Forwarded-Host`, `X-Forwarded-Uri` headers (if present) of the incoming
+request.
 
 **Example**
 

src/sidebar.js

@@ -446,7 +446,7 @@ module.exports = {
               ]
             },
             {
-              Guides: ['oathkeeper/configure-deploy']
+              Guides: ['oathkeeper/configure-deploy', "oathkeeper/guides/traefik-proxy-integration"]
             },
             'oathkeeper/reference/api',
             {