From 1915dbda874b43c799a1064ad20dc2d07320fc6d Mon Sep 17 00:00:00 2001
From: Dimitrij Drus <dadrus@gmx.de>
Date: Mon, 14 Feb 2022 11:19:18 +0100
Subject: [PATCH] docs: traefik + oathkeeper (#577)

This PR contains the documentation for the updates done in https://github.com/ory/oathkeeper/pull/904.
---
 .../guides/traefik-proxy-integration.md       | 38 +++++++++++++++++++
 docs/oathkeeper/index.md                      | 11 ++++--
 docs/oathkeeper/pipeline/error.md             |  5 ++-
 src/sidebar.js                                |  2 +-
 4 files changed, 50 insertions(+), 6 deletions(-)
 create mode 100644 docs/oathkeeper/guides/traefik-proxy-integration.md

diff --git a/docs/oathkeeper/guides/traefik-proxy-integration.md b/docs/oathkeeper/guides/traefik-proxy-integration.md
new file mode 100644
index 000000000..cb20d6f96
--- /dev/null
+++ b/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
+```
diff --git a/docs/oathkeeper/index.md b/docs/oathkeeper/index.md
index 1c90f4a6c..0f441af54 100644
--- a/docs/oathkeeper/index.md
+++ b/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
diff --git a/docs/oathkeeper/pipeline/error.md b/docs/oathkeeper/pipeline/error.md
index 901247895..62884db99 100644
--- a/docs/oathkeeper/pipeline/error.md
+++ b/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**
 
diff --git a/src/sidebar.js b/src/sidebar.js
index 941bca70e..43a7f94fb 100644
--- a/src/sidebar.js
+++ b/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',
             {