libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases Packages Activity Actions

Edits to the reverse proxy

Browse source 
Suggested deny and allow instead of black/white listed

Closes #9982
This commit is contained in:
AndyMunro 2022-02-03 15:42:04 -05:00 committed by Stian Thorgersen
parent 0f3293cf00
commit d8c5f9e2fc
1 changed files with 33 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
docs/guides/src/main/server/reverseproxy.adoc
View file

@ -4,38 +4,49 @@
<@tmpl.guide <@tmpl.guide
title="Configuring a reverse proxy" title="Configuring a reverse proxy"
summary="Learn how to configure Keycloak together with a reverse proxy, api gateway or load balancer." summary="Learn how to configure Keycloak together with a reverse proxy, api gateway, or load balancer."
includedOptions="proxy 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 TLS termination in your specific environment: Distributed environments frequently require the use of a reverse proxy.
For Keycloak, your choice of proxy modes depends on the TLS termination in your environment.
== Available proxy modes == Proxy modes
The `none` mode disables proxy support. It is the default mode. The following proxy modes are available:
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. none:: Disables proxy support.
It is the default mode.
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. edge:: 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 `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. reencrypt:: 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.
Different keys and certificates are used on the reverse proxy as well as on Keycloak.
passthrough:: 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.
The proxy instead is forwarding 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.
== Configure the proxy mode in Keycloak == Configure the proxy mode in Keycloak
To select the proxy mode, run: To select the proxy mode, enter this command:
<@kc.start parameters="--proxy <mode>"/> <@kc.start parameters="--proxy <mode>"/>
== Configure the reverse proxy == Configure the reverse proxy
Make sure your reverse proxy is configured correctly. To do so, please: Make sure your reverse proxy is configured correctly by performing these actions:
* Properly set X-Forwarded-For and X-Forwarded-Proto HTTP headers.
* Set the X-Forwarded-For and X-Forwarded-Proto HTTP headers.
* Preserve the original 'Host' HTTP header. * Preserve the original 'Host' HTTP header.
Please consult the documentation of your reverse proxy on how to set these headers. To set these headers, consult the documentation for your reverse proxy.
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 this header is incorrectly configured, rogue clients can set this header and trick Keycloak into thinking the client is connected from a different IP address than the actual address.
This precaution can more be critical if you do any deny or allow listing of IP addresses.
=== Exposed path recommendations === Exposed path recommendations
When using a reverse proxy, not all paths have to be exposed in order for Keycloak to work correctly. The recommendations on which paths to expose and which not to expose are as follows: When using a reverse proxy, Keylcoak only requires certain paths need to be exposed.
The following table shows the recommended paths to expose.
|=== |===
|Keycloak Path|Reverse Proxy Path|Exposed|Reason |Keycloak Path|Reverse Proxy Path|Exposed|Reason
@ -43,32 +54,32 @@ When using a reverse proxy, not all paths have to be exposed in order for Keyclo
|/ |/
|- |-
|No |No
|When exposing all paths, admin paths are exposed unnecessarily |When exposing all paths, admin paths are exposed unnecessarily.
|/admin/ |/admin/
| - | -
|No |No
|Exposed admin paths lead to an unnecessary attack vector |Exposed admin paths lead to an unnecessary attack vector.
|/js/ |/js/
| - | -
|No |No
|It's good practice to not use external js for the javascript client, but bake it into your public client instead |A good practice is to not use external js for the javascript client, but bake it into your public client instead.
|/welcome/ |/welcome/
| - | -
|No |No
|No need to expose the welcome page after initial installation. |No need exists to expose the welcome page after initial installation.
|/realms/ |/realms/
|/realms/ |/realms/
|Yes |Yes
|Needed to work correctly (e.g. oidc endpoints) |This path is needed to work correctly, for example, for OIDC endpoints.
|/resources/ |/resources/
|/resources/ |/resources/
|Yes |Yes
|Needed to serve assets correctly. May be served from a CDN instead of the Keycloak path. |This path is needed to serve assets correctly. It may be served from a CDN instead of the Keycloak path.
|/robots.txt |/robots.txt
|/robots.txt |/robots.txt
@ -76,6 +87,7 @@ When using a reverse proxy, not all paths have to be exposed in order for Keyclo
|Search engine rules |Search engine rules
|=== |===
We assume you run Keycloak on the root path `/` on your reverse proxy/gateways public API. If not, prefix the path with your desired one. We assume you run Keycloak on the root path `/` on your reverse proxy/gateway's public API.
If not, prefix the path with your desired one.
</@tmpl.guide> </@tmpl.guide>