115 lines
No EOL
6.5 KiB
Text
115 lines
No EOL
6.5 KiB
Text
[[_applicationclustering]]
|
|
==== Application Clustering
|
|
|
|
ifeval::[{project_community}==true]
|
|
This chapter is related to supporting clustered applications deployed to JBoss EAP, WildFly and JBoss AS.
|
|
endif::[]
|
|
ifeval::[{project_product}==true]
|
|
This chapter is related to supporting clustered applications deployed to JBoss EAP.
|
|
endif::[]
|
|
|
|
There are a few options available depending on whether your application is:
|
|
|
|
* Stateless or stateful
|
|
* Distributable (replicated http session) or non-distributable
|
|
* Relying on sticky sessions provided by load balancer
|
|
* Hosted on same domain as {project_name}
|
|
|
|
Dealing with clustering is not quite as simple as for a regular application. Mainly due to the fact that both the browser and the server-side application
|
|
sends requests to {project_name}, so it's not as simple as enabling sticky sessions on your load balancer.
|
|
|
|
===== Stateless token store
|
|
|
|
By default, the web application secured by {project_name} uses the HTTP session to store security context. This means that you either have to
|
|
enable sticky sessions or replicate the HTTP session.
|
|
|
|
As an alternative to storing the security context in the HTTP session the adapter can be configured to store this in a cookie instead. This is useful if you want
|
|
to make your application stateless or if you don't want to store the security context in the HTTP session.
|
|
|
|
To use the cookie store for saving the security context, edit your applications `WEB-INF/keycloak.json` and add:
|
|
[source,json]
|
|
----
|
|
"token-store": "cookie"
|
|
----
|
|
|
|
NOTE: The default value for `token-store` is `session`, which stores the security context in the HTTP session.
|
|
|
|
One limitation of using the cookie store is that the whole security context is passed in the cookie for every HTTP request. This may impact performance.
|
|
|
|
Another small limitation is limited support for Single-Sign Out. It works without issues if you init servlet logout (HttpServletRequest.logout) from the
|
|
application itself as the adapter will delete the KEYCLOAK_ADAPTER_STATE cookie. However, back-channel logout initialized from a different application isn't
|
|
propagated by {project_name} to applications using cookie store. Hence it's recommended to use a short value for the access token timeout (for example 1 minute).
|
|
|
|
===== Relative URI optimization
|
|
|
|
In deployment scenarios where {project_name} and the application is hosted on the same domain (through a reverse proxy or load balancer) it can be
|
|
convenient to use relative URI options in your client configuration.
|
|
|
|
With relative URIs the URI is resolved as relative to the URL used to access {project_name}.
|
|
|
|
For example if the URL to your application is `$$https://acme.org/myapp$$` and the URL to {project_name} is `$$https://acme.org/auth$$`, then you can use
|
|
the redirect-uri `/myapp` instead of `$$https://acme.org/myapp$$`.
|
|
|
|
===== Admin URL configuration
|
|
|
|
Admin URL for a particular client can be configured in the {project_name} Administration Console.
|
|
It's used by the {project_name} server to send backend requests to the application for various tasks, like logout users or push revocation policies.
|
|
|
|
For example the way backchannel logout works is:
|
|
|
|
. User sends logout request from one application
|
|
. The application sends logout request to {project_name}
|
|
. The {project_name} server invalidates the user session
|
|
. The {project_name} server then sends a backchannel request to application with an admin url that are associated with the session
|
|
. When an application receives the logout request it invalidates the corresponding HTTP session
|
|
|
|
If admin URL contains `${application.session.host}` it will be replaced with the URL to the node associated with the HTTP session.
|
|
|
|
[[_registration_app_nodes]]
|
|
===== Registration of application nodes
|
|
|
|
The previous section describes how {project_name} can send logout request to node associated with a specific HTTP session.
|
|
However, in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them.
|
|
For example to push a new not before policy to the application or to logout all users from the application.
|
|
|
|
In this case {project_name} needs to be aware of all application cluster nodes, so it can send the event to all of them.
|
|
To achieve this, we support auto-discovery mechanism:
|
|
|
|
. When a new application node joins the cluster, it sends a registration request to the {project_name} server
|
|
. The request may be re-sent to {project_name} in configured periodic intervals
|
|
. If the {project_name} server doesn't receive a re-registration request within a specified timeout then it automatically unregisters the specific node
|
|
. The node is also unregistered in {project_name} when it sends an unregistration request, which is usually during node shutdown or application undeployment.
|
|
This may not work properly for forced shutdown when undeployment listeners are not invoked, which results in the need for automatic unregistration
|
|
|
|
Sending startup registrations and periodic re-registration is disabled by default as it's only required for some clustered applications.
|
|
|
|
To enable the feature edit the `WEB-INF/keycloak.json` file for your application and add:
|
|
|
|
[source,json]
|
|
----
|
|
"register-node-at-startup": true,
|
|
"register-node-period": 600,
|
|
----
|
|
|
|
This means the adapter will send the registration request on startup and re-register every 10 minutes.
|
|
|
|
In the {project_name} Administration Console you can specify the maximum node re-registration timeout (should be larger than _register-node-period_ from
|
|
the adapter configuration). You can also manually add and remove cluster nodes in through the Adminstration Console, which is useful if you don't want to rely
|
|
on the automatic registration feature or if you want to remove stale application nodes in the event your not using the automatic unregistration feature.
|
|
|
|
[[_refresh_token_each_req]]
|
|
===== Refresh token in each request
|
|
|
|
By default the application adapter will only refresh the access token when it's expired. However, you can also configure the adapter to refresh the token on every
|
|
request. This may have a performance impact as your application will send more requests to the {project_name} server.
|
|
|
|
To enable the feature edit the `WEB-INF/keycloak.json` file for your application and add:
|
|
|
|
[source,json]
|
|
----
|
|
"always-refresh-token": true
|
|
----
|
|
|
|
NOTE: This may have a significant impact on performance. Only enable this feature if you can't rely on backchannel messages to propagate logout and not before
|
|
policies. Another thing to consider is that by default access tokens has a short expiration so even if logout is not propagated the token will expire within
|
|
minutes of the logout. |