diff --git a/docs/guides/server/hostname.adoc b/docs/guides/server/hostname.adoc index 2daeb3b40d..807f59d12e 100644 --- a/docs/guides/server/hostname.adoc +++ b/docs/guides/server/hostname.adoc @@ -46,9 +46,13 @@ As you can observe, the HTTPS protocol is the default choice, adhering to {proje The result of this configuration is that you can continue to access {project_name} at `https://my.keycloak.org` via HTTPS, while the proxy interacts with the instance using HTTP and port `8080`. -== Relying on a trusted proxy for dynamic URL resolution +== Using a reverse proxy -If you fully trust your proxy, the `proxy-headers` option is used to dynamically resolve the URL. +When a proxy is in use, the `proxy-headers` should be set. Depending on the hostname settings, some or all of the URL, may be dynamically determined. + +WARNING: If either `forwarded` or `xforwarded` is selected, make sure your reverse proxy properly sets and overwrites the `Forwarded` or `X-Forwarded-*` headers respectively. To set these headers, consult the documentation for your reverse proxy. Misconfiguration will leave {project_name} exposed to security vulnerabilities. + +=== Fully dynamic URLs. For example if your reverse proxy correctly sets the Forwarded header, and you don't want to hardcode the hostname, {project_name} can accommodate this. You simply need to initiate the server as follows: @@ -56,13 +60,21 @@ For example if your reverse proxy correctly sets the Forwarded header, and you d With this configuration, the server respects the value set by the Forwarded header. This also implies that all endpoints are dynamically resolved. +=== Partially dynamic URLs + The `proxy-headers` option can be also used to resolve the URL partially dynamically when the `hostname` option is not specified as a full URL. For example: <@kc.start parameters="--hostname my.keycloak.org --proxy-headers xforwarded"/> In this case, scheme, port and context path are resolved dynamically from X-Forwarded-* headers, while hostname is statically defined as `my.keycloak.org`. -WARNING: If either `forwarded` or `xforwarded` is selected, make sure your reverse proxy properly sets and overwrites the `Forwarded` or `X-Forwarded-*` headers respectively. To set these headers, consult the documentation for your reverse proxy. Misconfiguration will leave {project_name} exposed to security vulnerabilities. +=== Fixed URLs + +The `proxy-headers` is still relevant even when the `hostname` is set to a full URL as the headers are used to determine the origin of the request. For example: + +<@kc.start parameters="--hostname https://my.keycloak.org --proxy-headers xforwarded"/> + +In this case, while nothing is dynamically resolved from the X-Forwarded-* headers, the X-Forwarded-* headers are used to determine the correct origin of the request. == Exposing the Administration Console on a separate hostname @@ -142,6 +154,8 @@ As indicated in the previous sections, URLs can be resolved in several ways: the * If `hostname-admin` is configured, `hostname` must be set to a URL (not just hostname). Otherwise {project_name} would not know what is the correct frontend URL (incl. port etc.) when accessing the Admin Console. * If `hostname-backchannel-dynamic` is set to true, `hostname` must be set to a URL (not just hostname). Otherwise {project_name} would not know what is the correct frontend URL (incl. port etc.) when being access via the dynamically resolved bachchannel. +Additionally if hostname is configured, then hostname-strict is ignored. + == Troubleshooting To troubleshoot the hostname configuration, you can use a dedicated debug tool which can be enabled as: diff --git a/docs/guides/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc index 3fc23ed288..c51713905f 100644 --- a/docs/guides/server/reverseproxy.adoc +++ b/docs/guides/server/reverseproxy.adoc @@ -18,6 +18,8 @@ Distributed environments frequently require the use of a reverse proxy. {project * `forwarded` enables parsing of the `Forwarded` header as per https://www.rfc-editor.org/rfc/rfc7239.html[RFC7239]. * `xforwarded` enables parsing of non-standard `X-Forwarded-*` headers, such as `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Port`. +NOTE: If you are using a reverse proxy and do not set the `proxy-headers` option, then by default you will see 403 Forbidden responses to requests via the proxy that perform origin checking. + For example: <@kc.start parameters="--proxy-headers forwarded"/>