From 99e7208f36e2dfbc5d9e79c239dc4253d50d6019 Mon Sep 17 00:00:00 2001 From: Dominik Guhr <89905860+DGuhr@users.noreply.github.com> Date: Mon, 17 Jan 2022 12:45:06 +0100 Subject: [PATCH] new title, summary and headlines for proxy guide (#9572) Closes #9570 --- docs/guides/src/main/server/proxy.adoc | 29 +++++++++++++------------- docs/guides/src/main/templates/kc.adoc | 7 ------- 2 files changed, 14 insertions(+), 22 deletions(-) diff --git a/docs/guides/src/main/server/proxy.adoc b/docs/guides/src/main/server/proxy.adoc index 057c63cfe0..e0dec0f538 100644 --- a/docs/guides/src/main/server/proxy.adoc +++ b/docs/guides/src/main/server/proxy.adoc @@ -3,13 +3,14 @@ <#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" +title="Configuring a reverse proxy" +summary="Learn how to configure Keycloak together with a reverse proxy, api gateway or load balancer." priority=20 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: +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 TLS termination in your specific environment: +== Available proxy modes 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. @@ -18,22 +19,20 @@ The `reencrypt` mode requires communication through HTTPS between the proxy and 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: +== Configure the proxy mode in Keycloak +To select the proxy mode, run: -<@kc.all parameters="--proxy "/> +<@kc.start parameters="--proxy "/> -Please make sure your reverse proxy is configured correctly. To do so, please: +== Configure the reverse proxy +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. +* Properly set X-Forwarded-For and X-Forwarded-Proto HTTP headers. -* Configure your reverse proxy to preserve the original 'Host' HTTP header. +* Preserve the original 'Host' HTTP header. -Please consult the documentation of your specific reverse proxy on how to set these headers. +Please consult the documentation of your 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. +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"/> - - \ 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 dde5ec5e59..7b905d2d92 100644 --- a/docs/guides/src/main/templates/kc.adoc +++ b/docs/guides/src/main/templates/kc.adoc @@ -10,11 +10,4 @@ bin/kc.[sh|bat] build ${parameters} ---- bin/kc.[sh|bat] start ${parameters} ---- - - -<#macro all parameters> -[source,bash] ----- -bin/kc.[sh|bat] [build|start|start-dev] ${parameters} ----- \ No newline at end of file