Keycloak

1
<#import "/templates/guide.adoc" as tmpl>
2
<#import "/templates/kc.adoc" as kc>
3
<#import "/templates/options.adoc" as opts>
4
<#import "/templates/links.adoc" as links>
5

6
<@tmpl.guide
7
title="Using a reverse proxy"
8
summary="Learn how to configure {project_name} together with a reverse proxy, api gateway, or load balancer."
9
includedOptions="proxy proxy-* hostname-path hostname-url http-relative-path">
10

11
Distributed environments frequently require the use of a reverse proxy. {project_name} offers several options to securely integrate with such environments.
12

13
== Configure the reverse proxy headers
14

15
{project_name} will parse the reverse proxy headers based on the `proxy-headers` option which accepts several values:
16

17
* By default if the option is not specified, no reverse proxy headers are parsed.
18
* `forwarded` enables parsing of the `Forwarded` header as per https://www.rfc-editor.org/rfc/rfc7239.html[RFC7239].
19
* `xforwarded` enables parsing of non-standard `X-Forwarded-*` headers, such as `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Port`.
20

21
For example:
22

23
<@kc.start parameters="--proxy-headers forwarded"/>
24

25
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.
26

27
Take extra precautions to ensure that the client address is properly set by your reverse proxy via the `Forwarded` or `X-Forwarded-For` headers.
28
If this header is incorrectly configured, rogue clients can set this header and trick {project_name} into thinking the client is connected from a different IP address than the actual address. This precaution can be more critical if you do any deny or allow listing of IP addresses.
29

30
NOTE: When using the `xforwarded` setting, the `X-Forwarded-Port` takes precedence over any port included in the `X-Forwarded-Host`.
31

32
== Proxy modes
33
NOTE: The support for setting proxy modes is deprecated and will be removed in a future {project_name} release. Consider configuring accepted reverse proxy headers instead as described in the chapter above. For migration instructions consult the https://www.keycloak.org/docs/latest/upgrading/index.html#deprecated-proxy-option[Upgrading Guide].
34

35
For {project_name}, your choice of proxy modes depends on the TLS termination in your environment. The following proxy modes are available:
36

37
edge:: Enables communication through HTTP between the proxy and {project_name}.
38
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 {project_name} using HTTP.
39

40
reencrypt:: Requires communication through HTTPS between the proxy and {project_name}.
41
This mode is suitable for deployments where internal communication between the reverse proxy and {project_name} should also be protected.
42
Different keys and certificates are used on the reverse proxy as well as on {project_name}.
43

44
passthrough:: The proxy forwards the HTTPS connection to {project_name} without terminating TLS.
45
The secure connections between the server and clients are based on the keys and certificates used by the {project_name} server.
46

47
When in **edge** or **reencrypt** proxy mode, {project_name} will parse the following headers and expects the reverse proxy to set them:
48

49
* `Forwarded` as per https://www.rfc-editor.org/rfc/rfc7239.html[RFC7239]
50
* Non-standard `X-Forwarded-*`, such as `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Port`
51

52
=== Configure the proxy mode in {project_name}
53
To select the proxy mode, enter this command:
54

55
<@kc.start parameters="--proxy <mode>"/>
56

57
== Different context-path on reverse proxy
58

59
{project_name} assumes it is exposed through the reverse proxy under the same context path as {project_name} is configured for. By default {project_name} is exposed through the root (`/`), which means it expects to be exposed through the reverse proxy on `/` as well.
60
You can use `hostname-path` or `hostname-url` in these cases, for example using `--hostname-path=/auth` if {project_name} is exposed through the reverse proxy on `/auth`.
61

62
Alternatively you can also change the context path of {project_name} itself to match the context path for the reverse proxy using the `http-relative-path` option, which will change the context-path of {project_name} itself to match the context path used by the reverse proxy.
63

64
== Trust the proxy to set hostname
65

66
By default, {project_name} needs to know under which hostname it will be called. If your reverse proxy is configured to check for the correct hostname, you can set {project_name} to accept any hostname.
67

68
<@kc.start parameters="--proxy-headers=forwarded|xforwarded --hostname-strict=false"/>
69

70
== Enable sticky sessions
71

72
Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more {project_name} servers on private network.
73
For performance purposes, it may be useful if load balancer forwards all requests related to particular browser session to the same {project_name} backend node.
74

75
The reason is, that {project_name} is using Infinispan distributed cache under the covers for save data related to current authentication session and user session.
76
The Infinispan distributed caches are configured with two owners by default. That means that particular session is primarily stored on two cluster nodes and the other nodes need to lookup the session remotely if they want to access it.
77

78
For example if authentication session with ID 123 is saved in the Infinispan cache on node1, and then node2 needs to lookup this session, it needs to send the request to node1 over the network to return the particular session entity.
79

80
It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions. The workflow in the cluster environment with the public frontend load balancer and two backend {project_name} nodes can be like this:
81

82
* User sends initial request to see the {project_name} login screen
83

84
* This request is served by the frontend load balancer, which forwards it to some random node (eg. node1). Strictly said, the node doesn't need to be random, but can be chosen according to some other criterias (client IP address etc). It all depends on the implementation and configuration of underlying load balancer (reverse proxy).
85

86
* {project_name} creates authentication session with random ID (eg. 123) and saves it to the Infinispan cache.
87

88
* Infinispan distributed cache assigns the primary owner of the session based on the hash of session ID. See Infinispan documentation for more details around this. Let's assume that Infinispan assigned node2 to be the owner of this session.
89

90
* {project_name} creates the cookie AUTH_SESSION_ID with the format like <session-id>.<owner-node-id> . In our example case, it will be 123.node2 .
91

92
* Response is returned to the user with the {project_name} login screen and the AUTH_SESSION_ID cookie in the browser
93

94
From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 .
95

96
The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to sticky over the AUTH_SESSION_ID cookie. How exactly do this is dependent on your loadbalancer.
97

98
If your proxy supports session affinity without processing cookies from backend nodes, you should set the `spi-sticky-session-encoder-infinispan-should-attach-route` option
99
to `false` in order to avoid attaching the node to cookies and just rely on the reverse proxy capabilities.
100

101
<@kc.start parameters="--spi-sticky-session-encoder-infinispan-should-attach-route=false"/>
102

103
By default, the `spi-sticky-session-encoder-infinispan-should-attach-route` option value is `true` so that the node name is attached to
104
cookies to indicate to the reverse proxy the node that subsequent requests should be sent to.
105

106
=== Exposing the administration console
107

108
By default, the administration console URLs are created solely based on the requests to resolve the proper scheme, host name, and port. For instance,
109
if you are using the `edge` proxy mode and your proxy is misconfigured, backend requests from your TLS termination proxy are going to use plain HTTP and potentially cause the administration
110
console from being accessible because URLs are going to be created using the `http` scheme and the proxy does not support plain HTTP.
111

112
In order to proper expose the administration console, you should make sure that your proxy is setting the `X-Forwarded-*` headers herein mentioned in order
113
to create URLs using the scheme, host name, and port, being exposed by your proxy.
114

115
=== Exposed path recommendations
116
When using a reverse proxy, {project_name} only requires certain paths need to be exposed.
117
The following table shows the recommended paths to expose.
118

119
[%autowidth]
120
|===
121
|{project_name} Path|Reverse Proxy Path|Exposed|Reason
122

123
|/
124
|-
125
|No
126
|When exposing all paths, admin paths are exposed unnecessarily.
127

128
|/admin/
129
| -
130
|No
131
|Exposed admin paths lead to an unnecessary attack vector.
132

133
|/js/
134
| -
135
|Yes (see note below)
136
|Access to keycloak.js needed for "internal" clients, e.g. the account console
137

138
|/welcome/
139
| -
140
|No
141
|No need exists to expose the welcome page after initial installation.
142

143
|/realms/
144
|/realms/
145
|Yes
146
|This path is needed to work correctly, for example, for OIDC endpoints.
147

148
|/resources/
149
|/resources/
150
|Yes
151
|This path is needed to serve assets correctly. It may be served from a CDN instead of the {project_name} path.
152

153
|/robots.txt
154
|/robots.txt
155
|Yes
156
|Search engine rules
157

158
|/metrics
159
|-
160
|No
161
|Exposed metrics lead to an unnecessary attack vector.
162

163
|/health
164
|-
165
|No
166
|Exposed health checks lead to an unnecessary attack vector.
167

168
|===
169

170
[NOTE]
171
As it's true that the `js` path is needed for internal clients like the account console, it's good practice to use `keycloak.js` from a JavaScript package manager like npm or yarn for your external clients.
172

173
We assume you run {project_name} on the root path `/` on your reverse proxy/gateway's public API.
174
If not, prefix the path with your desired one.
175

176
=== Enabling client certificate lookup
177

178
When the proxy is configured as a TLS termination proxy the client certificate information can be forwarded to the server through specific HTTP request headers and then used to authenticate
179
clients. You are able to configure how the server is going to retrieve client certificate information depending on the proxy you are using.
180

181
The server supports some of the most commons TLS termination proxies such as:
182

183
[%autowidth]
184
|===
185
|Proxy|Provider
186

187
|Apache HTTP Server
188
|apache
189

190
|HAProxy
191
|haproxy
192

193
|NGINX
194
|nginx
195
|===
196

197
To configure how client certificates are retrieved from the requests you need to:
198

199
.Enable the corresponding proxy provider
200
<@kc.build parameters="--spi-x509cert-lookup-provider=<provider>"/>
201

202
.Configure the HTTP headers
203
<@kc.start parameters="--spi-x509cert-lookup-<provider>-ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup-<provider>-ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup-<provider>-certificate-chain-length=10"/>
204

205
When configuring the HTTP headers, you need to make sure the values you are using correspond to the name of the headers
206
forwarded by the proxy with the client certificate information.
207

208
The available options for configuring a provider are:
209

210
[%autowidth]
211
|===
212
|Option|Description
213

214
|ssl-client-cert
215
| The name of the header holding the client certificate
216

217
|ssl-cert-chain-prefix
218
| The prefix of the headers holding additional certificates in the chain and used to retrieve individual
219
certificates accordingly to the length of the chain. For instance, a value `CERT_CHAIN` will tell the server
220
to load additional certificates from headers `CERT_CHAIN_0` to `CERT_CHAIN_9` if `certificate-chain-length` is set to `10`.
221

222
|certificate-chain-length
223
| The maximum length of the certificate chain.
224

225
|trust-proxy-verification
226
| Enable trusting NGINX proxy certificate verification, instead of forwarding the certificate to {project_name} and verifying it in {project_name}.
227
|===
228

229
==== Configuring the NGINX provider
230

231
The NGINX SSL/TLS module does not expose the client certificate chain. {project_name}'s NGINX certificate lookup provider rebuilds it by using the {project_name} truststore.
232

233
If you are using this provider, see <@links.server id="keycloak-truststore"/> for how
234
to configure a {project_name} Truststore.
235

236
</@tmpl.guide>
237