From 6a4efaecb09e1dd693ebd8dd4ff5039c24c87c66 Mon Sep 17 00:00:00 2001
From: Jens Langhammer <jens.langhammer@beryju.org>
Date: Tue, 21 Jun 2022 22:26:17 +0200
Subject: [PATCH] website/docs: start troubleshooting page for forward auth

Signed-off-by: Jens Langhammer <jens.langhammer@beryju.org>
---
 .../troubleshooting/forward_auth/general.mdx  | 62 +++++++++++++++++++
 website/docusaurus.config.js                  |  6 +-
 website/sidebars.js                           | 12 ++++
 3 files changed, 78 insertions(+), 2 deletions(-)
 create mode 100644 website/docs/troubleshooting/forward_auth/general.mdx

diff --git a/website/docs/troubleshooting/forward_auth/general.mdx b/website/docs/troubleshooting/forward_auth/general.mdx
new file mode 100644
index 000000000..80c23651c
--- /dev/null
+++ b/website/docs/troubleshooting/forward_auth/general.mdx
@@ -0,0 +1,62 @@
+---
+title: General troubleshooting steps
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+## Set the log level to TRACE
+
+Setting the log level to trace configures the outpost to trace-log all the headers given in forward auth requests.
+
+This is helpful to confirm that certain required Headers are correctly forwarded from the reverse proxy.
+
+### When using the embedded Outpost
+
+Set the authentik log level to `TRACE`:
+
+<Tabs
+  groupId="platform"
+  defaultValue="docker-compose"
+  values={[
+    {label: 'docker-compose', value: 'docker-compose'},
+    {label: 'Kubernetes', value: 'kubernetes'},
+  ]}>
+  <TabItem value="docker-compose">
+Add the following block to your `.env` file:
+
+```shell
+AUTHENTIK_LOG_LEVEL=trace
+```
+
+Afterwards, run `docker-compose up -d`.
+
+  </TabItem>
+  <TabItem value="kubernetes">
+Add the following block to your `values.yml` file:
+
+```yaml
+authentik:
+    log_level: trace
+```
+
+Afterwards, upgrade helm release.
+
+  </TabItem>
+</Tabs>
+
+### When using a standard outpost
+
+Edit the outpost settings and set `log_level: trace`. This setting should propagate to the outpost instances within a couple seconds.
+
+## Ensure `/outpost.goauthentik.io` is accessible
+
+Everything under `/outpost.goauthentik.io` should be publicly accessible, as URLs under this path are used for authentication.
+
+To check this, run `curl -v https://app.company/outpost.goauthentik.io/ping`. A correct setup should contain output looking like this:
+
+```
+[...]
+< HTTP/2 204
+[...]
+```
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 9da48f732..2d9341c17 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -48,14 +48,16 @@ module.exports = {
                 },
                 {
                     type: "dropdown",
-                    label: `Version ${latestVersion}`,
+                    label: `Version: latest`,
                     position: "right",
                     items: releases.map((release) => {
                         const subdomain = release
                             .replace("releases/v", "")
                             .replace(".", "-");
+                        const label =
+                            "Version: " + release.replace("releases/", "");
                         return {
-                            label: release.replace("releases/", ""),
+                            label: label,
                             href: `https://version-${subdomain}.goauthentik.io`,
                         };
                     }),
diff --git a/website/sidebars.js b/website/sidebars.js
index e693eb78d..28bc984ed 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -241,6 +241,18 @@ module.exports = {
                 description: "Troubleshooting various issues",
             },
             items: [
+                {
+                    type: "category",
+                    label: "Forward auth",
+                    items: ["troubleshooting/forward_auth/general"],
+                    link: {
+                        type: "generated-index",
+                        title: "Forward auth troubleshooting",
+                        slug: "troubleshooting/forward_auth",
+                        description:
+                            "Steps to help debug forward auth setups with various reverse proxies.",
+                    },
+                },
                 "troubleshooting/access",
                 "troubleshooting/emails",
                 "troubleshooting/login",