From 1cebd79f1c454235622ba0cb3c8195a38a9a1856 Mon Sep 17 00:00:00 2001
From: Dominik Guhr <dguhr@redhat.com>
Date: Fri, 17 Dec 2021 08:10:04 +0100
Subject: [PATCH] Solves [#9206] - Initial version for proxy documentation

---
 docs/guides/src/GENERATE-DOCS.md       | 17 ++++++++++++
 docs/guides/src/main/server/proxy.adoc | 38 ++++++++++++++++++++++++++
 docs/guides/src/main/templates/kc.adoc |  7 +++++
 3 files changed, 62 insertions(+)
 create mode 100644 docs/guides/src/GENERATE-DOCS.md
 create mode 100644 docs/guides/src/main/server/proxy.adoc

diff --git a/docs/guides/src/GENERATE-DOCS.md b/docs/guides/src/GENERATE-DOCS.md
new file mode 100644
index 0000000000..8c920e0d43
--- /dev/null
+++ b/docs/guides/src/GENERATE-DOCS.md
@@ -0,0 +1,17 @@
+To generate the docs, we use a maven plugin that transforms the guides from FreeMarker enabled AsciiDoc to pure AsciiDoc. This includes linking the options from the Configuration to expose them to FreeMarker templates. 
+
+FreeMarker macros are used heavily here to keep consistency throughout the guides, and to make the guides themselves as slim as possible.
+
+To help debugging, for now use the `DocsBuildDebugUtil.java` which has a main method that allows running this step outside of Maven.
+
+To build the guides, run: 
+```
+cd docs
+mvn clean install
+```
+After that you will have the following artifacts:
+
+- `docs/guides/target/generated-guides`: pure asciidoc generated versions of the guides
+- `docs/guides/target/generated-docs/index.html`: all guides in a single html file generated with asciidoc maven plugins. 
+
+_Note:_ The layout primarily serves as an example for now and is not how we will eventually present the documentation.
\ No newline at end of file
diff --git a/docs/guides/src/main/server/proxy.adoc b/docs/guides/src/main/server/proxy.adoc
new file mode 100644
index 0000000000..6e77b3747d
--- /dev/null
+++ b/docs/guides/src/main/server/proxy.adoc
@@ -0,0 +1,38 @@
+<#import "/templates/guide.adoc" as tmpl>
+<#import "/templates/kc.adoc" as kc>
+<#import "/templates/options.adoc" as opts>
+
+<@tmpl.guide
+title="Configuring Keycloak to run behind a reverse proxy"
+summary="Understand how to configure Keycloak when using a reverse proxy"
+includedOptions="proxy proxy.*">
+
+It is pretty common nowadays to use a reverse proxy in distributed environments. If you want to use Keycloak together with such a proxy, you can use different proxy modes depending on the proxy and TLS termination in your specific environment:
+
+The `none` mode disables proxy support. It is the default mode.
+
+The `edge` mode enables communication through HTTP between the proxy and Keycloak. This mode is suitable for deployments with a highly secure internal network where the reverse proxy keeps a secure connection (HTTP over TLS) with clients while communicating with Keycloak using HTTP.
+
+The `reencrypt` mode requires communication through HTTPS between the proxy and Keycloak. This mode is suitable for deployments where internal communication between the reverse proxy and Keycloak should also be protected, and different keys and certificates are used on the reverse proxy as well as on Keycloak.
+
+The `passthrough` mode enables communication through HTTP or HTTPS between the proxy and Keycloak. This mode is suitable for deployments where the reverse proxy is not terminating TLS, but only forwarding the requests to the Keycloak server so that secure connections between the server and clients are based on the keys and certificates used by the Keycloak server itself.
+
+Selecting the reverse proxy mode is done at runtime via:
+
+<@kc.all parameters="--proxy <mode>"/>
+
+Please make sure your reverse proxy is configured correctly. To do so, please:
+
+* Configure your reverse proxy to properly set X-Forwarded-For and X-Forwarded-Proto HTTP headers.
+
+* Configure your reverse proxy to preserve the original 'Host' HTTP header.
+
+Please consult the documentation of your specific reverse proxy on how to set these headers.
+
+_Note_: Take extra precautions to ensure that the X-Forwarded-For header is set by your reverse proxy. If it is not configured correctly, rogue clients can set this header themselves and trick Keycloak into thinking the client is connecting from a different IP address than it actually does. This may become really important if you are doing any black or white listing of IP addresses.
+
+Valid options for the proxy mode include:
+
+<@opts.expectedValues option="proxy"/>
+
+</@tmpl.guide>
\ No newline at end of file
diff --git a/docs/guides/src/main/templates/kc.adoc b/docs/guides/src/main/templates/kc.adoc
index 7b905d2d92..dde5ec5e59 100644
--- a/docs/guides/src/main/templates/kc.adoc
+++ b/docs/guides/src/main/templates/kc.adoc
@@ -10,4 +10,11 @@ bin/kc.[sh|bat] build ${parameters}
 ----
 bin/kc.[sh|bat] start ${parameters}
 ----
+</#macro>
+
+<#macro all parameters>
+[source,bash]
+----
+bin/kc.[sh|bat] [build|start|start-dev] ${parameters}
+----
 </#macro>
\ No newline at end of file