From 6e91ee0648696fe8f47c9cad694669177f944fe3 Mon Sep 17 00:00:00 2001
From: Dimitrij Drus <dimitrij.drus@innoq.com>
Date: Fri, 4 Feb 2022 13:00:24 +0100
Subject: [PATCH] more docu

---
 docs/docs/guides/traefik-proxy-integration.md | 20 +++++++++++--------
 docs/docs/index.md                            | 11 ++++++----
 docs/docs/pipeline/error.md                   |  5 ++++-
 3 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/docs/docs/guides/traefik-proxy-integration.md b/docs/docs/guides/traefik-proxy-integration.md
index 12a21fa481..cb20d6f968 100644
--- a/docs/docs/guides/traefik-proxy-integration.md
+++ b/docs/docs/guides/traefik-proxy-integration.md
@@ -3,13 +3,20 @@ 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).
+[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
+
+- 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):
 
@@ -29,6 +36,3 @@ service:
     - traefik.http.routers.service.middlewares=oathkeeper
     # further labels
 ```
-
-
-
diff --git a/docs/docs/index.md b/docs/docs/index.md
index 15e7f71de7..83328e48ba 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -188,10 +188,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
diff --git a/docs/docs/pipeline/error.md b/docs/docs/pipeline/error.md
index 901247895e..62884db998 100644
--- a/docs/docs/pipeline/error.md
+++ b/docs/docs/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**