upstream/keycloak
1
0
Fork 0
mirror of https://github.com/keycloak/keycloak.git synced 2026-06-09 00:52:07 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 16

Edits to caching topic (#9988)

Browse source 
Closes #9968
This commit is contained in:
andymunro 2022-02-07 03:22:11 -05:00 committed by GitHub
parent d9c8cb30a5
commit aed6e8cd5b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 44 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
docs/guides/src/main/server/caching.adoc
View file

@ -7,26 +7,31 @@ title="Configuring distributed caches"
summary="Understand how to configure the caching layer"
includedOptions="cache cache-*">
Keycloak is designed for high availability and multi-node clustered setups. The current distributed cache implementation is built on top of https://infinispan.org[Infinispan], a high-performance, distributable in-memory data grid.
Keycloak is designed for high availability and multi-node clustered setups.
The current distributed cache implementation is built on top of https://infinispan.org[Infinispan], a high-performance, distributable in-memory data grid.
All available cache options are build options, so they need to be applied to a `build` of Keycloak before starting.
== Enable distributed caching
Caching is enabled per default when you start Keycloak in production mode, using the `start` command. This will automatically discover other Keycloak nodes in your network. To explicitly enable distributed infinispan caching, use:
When you start Keycloak in production mode, by using the `start` command, caching is enabled and all Keycloak nodes in your network are discovered.
To explicitly enable distributed infinispan caching, enter this command:
<@kc.build parameters="--cache=ispn"/>
When you start Keycloak in development mode, using the `start-dev` command, Keycloak defaults to only use local caches using `--cache=local` instead. Using the `local` cache mode is intended only for development and testing purposes.
When you start Keycloak in development mode, by using the `start-dev` command, Keycloak uses only local caches, applying the `--cache=local` option.
The `local` cache mode is intended only for development and testing purposes.
== Configure Caches
== Configuring caches
Keycloak provides a cache configuration file with sensible defaults located at `conf/cache-ispn.xml`.
The cache configuration is a regular https://infinispan.org/docs/stable/titles/configuring/configuring.html[Infinispan] configuration file.
The cache configuration is a regular https://infinispan.org/docs/stable/titles/configuring/configuring.html[Infinispan configuration file].
=== Overview: Cache types and Defaults
=== Cache types and defaults
.Local caches
Keycloak caches persistent data locally to avoid unnecessary database requests. The caches used are:
Keycloak caches persistent data locally to avoid unnecessary database requests.
The following caches are used:
* realms
* users
@ -34,28 +39,34 @@ Keycloak caches persistent data locally to avoid unnecessary database requests.
* keys
.Invalidation of local caches
Local caching improves performance, but adds a challenge in multi-node setups: When one Keycloak node updates data in the shared database, all other nodes need to be aware of it, so they invalidate that data from their caches. The `work` cache is used for sending these invalidation messages.
Local caching improves performance, but adds a challenge in multi-node setups.
When one Keycloak node updates data in the shared database, all other nodes need to be aware of it, so they invalidate that data from their caches.
The `work` cache is used for sending these invalidation messages.
.Authentication sessions
Authentication sessions are started when an unauthenticated user or service tries to login to Keycloak. The `authenticationSessions` distributed cache is used to save data during authentication of particular user.
Authentication sessions are started when an unauthenticated user or service tries to log in to Keycloak.
The `authenticationSessions` distributed cache is used to save data during authentication of a particular user.
.User sessions
There are four distributed caches for sessions of authenticated users and services:
The following are the distributed caches for sessions of authenticated users and services:
* sessions
* clientSessions
* offlineSessions
* offlineClientSessions
These caches are used to save data about user sessions, and clients attached to the sessions.
These caches are used to save data about user sessions and clients attached to the sessions.
.Password brute force detection
The `loginFailures` distributed cache is used to track data about failed login attempts. This cache is needed for the Brute Force Protection feature to work correctly in a multi-node Keycloak setup.
The `loginFailures` distributed cache is used to track data about failed login attempts.
This cache is needed for the Brute Force Protection feature to work in a multi-node Keycloak setup.
.Action tokens
Action tokens are used for scenarios when a user needs to confirm an action asynchronously, for example in the emails sent by the forgot password flow. The `actionTokens` distributed cache is used to track metadata about action tokens.
Action tokens are used for scenarios when a user needs to confirm an action asynchronously, for example in the emails sent by the forgot password flow.
The `actionTokens` distributed cache is used to track metadata about action tokens.
The following table gives an overview of the specific caches Keycloak uses. These caches are configured in `conf/cache-ispn.xml`:
The following table gives an overview of the specific caches Keycloak uses.
You configure these caches in `conf/cache-ispn.xml`:
|====
|Cache name|Cache Type|Description
@ -73,22 +84,28 @@ The following table gives an overview of the specific caches Keycloak uses. Thes
|actionTokens|Distributed|Caches action Tokens
|====
Local caches for realms, users and authorization are configured to have 10000 entries per default. The local key cache can hold up to 1000 entries per default and defaults to expire every 1h, so keys are forced to be periodically downloaded from external clients or identity providers.
Local caches for realms, users, and authorization are configured to have 10,000 entries per default.
The local key cache can hold up to 1,000 entries per default and defaults to expire every one hour.
Therefore, keys are forced to be periodically downloaded from external clients or identity providers.
All distributed caches are set to have 2 owners per default, meaning 2 nodes having a copy of the specific cache entries. Non-owner nodes query the owners of a specific cache to obtain data. When both owner nodes are offline, all data gets lost. This usually leads to users being logged out at the next request and having to login again.
Each distributed cache has two owners per default, which means that two nodes have a copy of the specific cache entries.
Non-owner nodes query the owners of a specific cache to obtain data.
When both owner nodes are offline, all data is lost.
This situation usually leads to users being logged out at the next request and having to log in again.
=== Specify your own cache configuration file
To specify your own cache configuration file, use:
To specify your own cache configuration file, enter this command:
<@kc.build parameters="--cache-config-file=my-cache-file.xml"/>
== Transport stacks
Transport stacks ensure that distributed cache nodes in a cluster communicate in a reliable fashion. Keycloak supports a wide range of transport stacks:
Transport stacks ensure that distributed cache nodes in a cluster communicate in a reliable fashion.
Keycloak supports a wide range of transport stacks:
<@opts.expectedValues option="cache-stack"/>
To apply a specific cache stack, use:
To apply a specific cache stack, enter this command:
<@kc.build parameters="--cache-stack=<stack>"/>
@ -104,8 +121,10 @@ The following table shows transport stacks that are available without any furthe
|===
=== Additional transport stacks
The following table shows transport stacks that are supported by Keycloak, but need some extra steps to work. Note that all of these are _not_ Kubernetes / OpenShift stacks, so you don't need to enable the "google" stack if you want to run Keycloak on top of Googles Kubernetes engine. In that case, use the `kubernetes` stack.
Instead, when you have a distributed cache setup running on AWS EC2 instances, you'd need to set the stack to `ec2`, because ec2 does not support a default discovery mechanism such as `UDP`.
The following table shows transport stacks that are supported by Keycloak, but need some extra steps to work.
Note that _none_ of these stacks are Kubernetes / OpenShift stacks, so no need exists to enable the "google" stack if you want to run Keycloak on top of the Google Kubernetes engine.
In that case, use the `kubernetes` stack.
Instead, when you have a distributed cache setup running on AWS EC2 instances, you would need to set the stack to `ec2`, because ec2 does not support a default discovery mechanism such as `UDP`.
|===
|Stack name|Transport protocol|Discovery
@ -114,13 +133,14 @@ Instead, when you have a distributed cache setup running on AWS EC2 instances, y
|azure|TCP|AZURE_PING
|===
For the cloud vendor specific stacks to work, you have to provide additional dependencies to Keycloak. You can find more information, including Links to repositories providing the additional dependencies, in the https://infinispan.org/docs/dev/titles/embedding/embedding.html#jgroups-cloud-discovery-protocols_cluster-transport[official Infinispan documentation].
Cloud vendor specific stacks have additional dependencies for Keycloak.
For more information and links to repositories with these dependencies, see the https://infinispan.org/docs/dev/titles/embedding/embedding.html#jgroups-cloud-discovery-protocols_cluster-transport[Infinispan documentation].
To provide the dependencies to Keycloak, put the respective JAR in the `providers` directory and `build` Keycloak afterwards, using
To provide the dependencies to Keycloak, put the respective JAR in the `providers` directory and `build` Keycloak by entering this command:
<@kc.build parameters="--cache-stack=<ec2|google|azure>"/>
=== Securing cache communication
The current Infinispan cache implementation should be secured by various security measures such as RBAC, ACLs and Transport stack encryption. Please refer to the https://infinispan.org/docs/dev/titles/security/security.html#[Infinispan security guide] for more information about securing cache communication.
The current Infinispan cache implementation should be secured by various security measures such as RBAC, ACLs, and Transport stack encryption. For more information about securing cache communication, see the https://infinispan.org/docs/dev/titles/security/security.html#[Infinispan security guide].
</@tmpl.guide>