Struggling with Keycloak performance? Here’s a quick guide to improve it. These 8 strategies can help you handle large-scale user authentication and authorization efficiently:
- Basic Setup: Configure server settings like memory allocation, thread pool size, and connection timeouts.
- Database Optimization: Use supported databases (e.g., PostgreSQL, Aurora) and tune connection pools for better performance.
- Cache Settings: Set up efficient caching (local, distributed) and configure limits for high traffic.
- Server Scaling: Use multi-server deployments with Kubernetes and auto-scaling rules for peak loads.
- System Resources: Optimize Java parameters, CPU, and memory allocation for stable performance.
- Network Setup: Secure HTTPS, use reverse proxies, and configure proxy headers for efficiency.
- Performance Tracking: Monitor metrics like login rates and resource usage with tools like Prometheus.
- Advanced Optimization: Tailor settings for specific use cases and workloads.
Key takeaway: A well-optimized Keycloak setup can reduce login times, improve database efficiency, and handle thousands of concurrent requests. Start by fine-tuning your server and database configurations, then scale and monitor as needed.
KEYCLOAK Upgrading and Migration – Frequently Asked …
1. Basic Keycloak Setup
Fine-tune critical settings during the initial setup to avoid performance issues down the line.
Server Image Setup
Use Keycloak’s build command to customize your server image. Key parameters to configure include:
- HTTP/HTTPS Settings: Set up port mappings and SSL configurations.
- Memory Allocation: Specify initial (
-Xms) and maximum (-Xmx) heap sizes. - Thread Pool Size: Adjust based on the number of concurrent users you expect.
- Connection Timeouts: Define suitable timeout durations for various operations.
Here’s an example production configuration:
KC_DB_URL_HOST=localhost
KC_DB_URL_DATABASE=keycloak
KC_DB_USERNAME=admin
KC_DB_PASSWORD=password
KC_HOSTNAME=auth.example.com
JAVA_OPTS_APPEND="-Xms1024m -Xmx2048m"
Main Config Files
In the keycloak.conf file, ensure you set the following key parameters:
# Database Configuration
db=postgres
db-url=jdbc:postgresql://localhost/keycloak
db-username=admin
db-password=password
# Connection Pool Settings
db-pool-initial-size=10
db-pool-min-size=10
db-pool-max-size=100
# HTTP Settings
http-enabled=true
http-port=8080
https-port=8443
System Variables
Set these environment variables to fine-tune your setup:
| Variable Name | Purpose | Recommended Value |
|---|---|---|
| KC_DB_POOL_SIZE | Database connection pool size | 50 |
| KC_TRANSACTION_XA_ENABLED | Support for XA transactions | false |
| KC_HTTP_RELATIVE_PATH | Context path for HTTP endpoints | /auth |
| KC_HOSTNAME_STRICT | Enforce strict hostname rules | false |
For environments with heavy traffic, remember to adjust memory limits (-Xms, -Xmx), optimize thread pool settings, and set proper connection/session timeouts.
Once these basics are in place, you can move on to configuring your database for better performance.
2. Database Setup
Choose the Right Database
When setting up a database for production, it’s essential to use a reliable and supported database. Here’s a list of supported production databases:
| Database Type | Version |
|---|---|
| PostgreSQL | 17 |
| Amazon Aurora PostgreSQL | 16.1 |
| MariaDB Server | 11.4 |
| MySQL | 8.4 |
| Oracle Database | 23.5 |
| Microsoft SQL Server | 2022 |
PostgreSQL, particularly Amazon Aurora PostgreSQL, is known for its efficient connection handling in Multi-AZ deployments.
“The server has built-in support for different databases.” – Keycloak Documentation
A real-world example: In March 2023, GitLab migrated its PostgreSQL to Google Cloud SQL. This change reduced replication lag from 15 seconds to under 1 second and improved performance by 30% across a 2TB database.
Once you’ve chosen the right database, move on to configuring connection pools to handle concurrent requests.
Set Up Connection Pools
Connection pools are critical for managing database load. Use the following settings in your keycloak.conf file to configure them:
db-pool-initial-size=20
db-pool-min-size=20
db-pool-max-size=100
- Set the initial and minimum pool sizes to handle the baseline load effectively.
- Adjust the maximum pool size based on your server’s capacity.
- Regularly monitor connection usage and tweak these values as needed.
Database Performance Tuning
To get the best performance out of your database, focus on these key areas:
- Index Optimization: Add indexes to columns that are queried frequently.
- Query Performance: Enable query logging to identify and address slow-running queries.
- Character Encoding: Ensure Unicode support is configured appropriately for your database.
- Scheduled Maintenance: Perform these tasks during off-peak hours:
- Vacuum operations (for PostgreSQL)
- Rebuilding indexes
- Updating statistics
- Cleaning up dead connections
These steps can help maintain a responsive and efficient database environment.
3. Cache Settings
Multi-Server Caching
Efficient caching plays a key role in keeping authentication and session management fast. For distributed caching in production, use the following command:
bin/kc.sh build --cache=ispn
Keycloak offers three main cache types, each serving a specific purpose:
| Cache Type | Purpose | Default Capacity |
|---|---|---|
| Local | Stores realm, user, and authorization data | 10,000 entries |
| Distributed | Manages sessions and authentication | Based on node count |
| Work | Handles cross-node invalidation messages | Replicated across nodes |
To match your infrastructure, optimize the transport stack. Use the appropriate command for your environment:
- Kubernetes:
bin/kc.sh build --cache-stack=kubernetes - Amazon EC2:
bin/kc.sh build --cache-stack=ec2 - Microsoft Azure:
bin/kc.sh build --cache-stack=azure - Google Cloud:
bin/kc.sh build --cache-stack=google
Once this is set up, configure cache limits to maximize resource efficiency.
Cache Limits
For a base configuration, a pod managing 10,000 cached sessions requires about 1,250 MB of RAM. In high-traffic environments with more than 2,500 concurrent clients, adjust the cache sizes as follows:
- Set the users cache size to 2× the number of concurrent clients.
- Set the realms cache size to 4× the number of concurrent clients.
Modify these settings in the conf/cache-ispn.xml file. For example:
<local-cache name="users">
<memory max-count="20000"/>
</local-cache>
<local-cache name="realms">
<memory max-count="40000"/>
</local-cache>
To monitor performance, enable statistics by adding statistics="true" to your cache configurations. This will help you track cache hit rates and pinpoint bottlenecks.
By default, distributed cache entries are stored on 2 nodes. You can adjust this as needed:
<distributed-cache owners="2" segments="20" name="sessions">
<memory max-count="100000"/>
</distributed-cache>
Finally, set up session affinity in your load balancer. This ensures users are directed to the node holding their cached session data, reducing unnecessary state transfers.
sbb-itb-9d854a3
4. Server Scaling
Once you’ve optimized the basics, the next step is scaling Keycloak to maintain performance as demand grows.
Add More Servers
Scaling Keycloak requires addressing its stateful nature. Start by deploying multiple Keycloak instances with Kubernetes Pod anti-affinity rules. This setup prevents pods from running on the same node, improving fault tolerance. Separate the cache component by deploying it as an independent Infinispan Cache Pod. Here’s an example configuration for deploying Keycloak replicas:
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: keycloak
spec:
replicas: 3
selector:
matchLabels:
app: keycloak
template:
spec:
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- topologyKey: "kubernetes.io/hostname"
Auto-Scaling Rules
To handle fluctuating workloads, set up a Horizontal Pod Autoscaler (HPA). The HPA adjusts the number of Keycloak instances based on metrics like CPU usage, memory consumption, and response times. Here are some tips for configuring your HPA:
- Allocate 150% extra CPU capacity to manage sudden spikes.
- Set
minReplicasto handle your baseline traffic. - Adjust
maxReplicasbased on available resources. - Use cooldown periods to avoid frequent scaling up and down.
These settings help maintain stability and efficiency during scaling.
Multi-Server Management
StatefulSets are key for managing multiple servers. They ensure that pod names and network identities remain consistent, which is critical for distributed caching. Here’s an example of an update strategy for managing clusters:
spec:
updateStrategy:
type: RollingUpdate
podManagementPolicy: Parallel
volumeClaimTemplates:
- metadata:
name: keycloak-data
spec:
accessModes: [ "ReadWriteOnce" ]
resources:
requests:
storage: 10Gi
To maintain performance, monitor cluster health using custom metrics. Keep in mind that performance may drop when scaling across many pods, especially in multi-datacenter setups. Regularly review and tweak your scaling policies to ensure efficient resource use and stable response times.
5. System Resources
Efficiently managing system resources is crucial for maintaining Keycloak’s performance, beyond just configuration adjustments.
Java Settings
To ensure consistent performance, set fixed heap sizes in your JVM configuration. Below is a table outlining key JVM parameters and their roles:
| Parameter | Setting | Purpose |
|---|---|---|
-Xms and -Xmx |
Same value, 25% above tested maximum | Allocates a fixed heap size |
-XX:+UseG1GC |
Enabled | Activates the G1 garbage collector |
-XX:+UseLargePages |
Enabled | Improves memory-intensive operations |
-XX:+AggressiveOpts |
Enabled | Enables performance optimizations |
Here’s an example of how to apply these settings in your startup script:
JAVA_OPTS="-Xms2048m -Xmx2048m -XX:+UseG1GC -XX:+UseLargePages -XX:+AggressiveOpts"
“Configuring optimal JVM options for your applications and JBoss EAP environment is one of the most fundamental ways to tune performance.” – Red Hat Product Documentation
Additionally, ensure that your CPU and memory settings align with your workload requirements.
CPU and Memory Limits
Follow these guidelines for resource allocation:
- Allocate 1 vCPU for every:
- 15 password logins per second
- 120 client credential grants per second
- 120 refresh token requests per second
- Memory requirements start at 1,250 MB RAM for a basic Pod setup. Use 70% of the memory for the heap and reserve around 300 MB for non-heap operations.
Here’s an example of resource limit configuration:
resources:
requests:
cpu: "3"
memory: "1250Mi"
limits:
cpu: "7.5"
memory: "1360Mi"
To ensure your system is running efficiently, use Keycloak’s built-in metrics to monitor performance:
keycloak_user_events_total: Tracks login events.keycloak_credentials_password_hashing_validations_total: Monitors password validation processes.
6. Network Setup
Configuring Keycloak’s network settings is crucial for better performance and security. This section outlines essential network configurations to help you achieve both.
HTTPS Setup
Securing data exchange between Keycloak and applications starts with HTTPS. You can customize the HTTPS port and set up your reverse proxy for SSL termination and header management. This reduces server load while keeping data secure.
Here’s how to configure HTTPS using PEM files:
bin/kc.sh start \
--https-certificate-file=/path/to/certfile.pem \
--https-certificate-key-file=/path/to/keyfile.pem
Key recommendations for HTTPS setup:
| Configuration | Recommendation | Purpose |
|---|---|---|
| Certificate Reload | Every 60 minutes | Ensures certificates and keys stay updated automatically |
| Password Storage | Use vaults or mounted secrets | Prevents storing plaintext keystore passwords |
| Protocol Support | TLS 1.2 and above | Ensures compliance with modern security standards |
“For production environments, you should never expose Keycloak endpoints through HTTP, as sensitive data is at the core of what Keycloak exchanges with other applications.”
Configuring your reverse proxy alongside HTTPS helps improve both security and performance.
Proxy Configuration
A reverse proxy adds an extra layer of security and can also enhance performance. Make sure to expose only the necessary paths for Keycloak to function correctly:
| Path | Expose | Purpose |
|---|---|---|
| /realms/ | Yes | Needed for OIDC endpoints |
| /resources/ | Yes | Serves assets (can leverage a CDN) |
| /admin/ | No | Avoid exposing; it poses a security risk |
| /metrics | No | For internal monitoring only |
| /health | No | For internal health checks only |
Tips to optimize proxy performance:
- Configure proxy headers: Use the following command to set up forwarded headers:
bin/kc.sh start --proxy-headers=forwarded - Enable sticky sessions: Use the
AUTH_SESSION_IDcookie to ensure consistent routing in clustered environments. - Set trusted proxy addresses: Define trusted proxy IPs or ranges for better security:
bin/kc.sh start --proxy-trusted-addresses=10.0.0.1,192.168.1.0/24
An update in March 2023 improved the handling of the proxy-headers option. This change led to a 20% drop in support tickets, faster deployments (by 15%), and fewer 403 errors during origin checks.
7. Performance Tracking
After setting up and scaling your system, the next step is ensuring everything runs smoothly. Performance tracking helps you spot issues early and keep operations steady.
Monitor Server Health
Use Prometheus and Grafana to keep an eye on critical metrics. Here are some key ones to track:
| Metric Name | Purpose | Recommended Threshold |
|---|---|---|
| keycloak_user_events_total | Password-based logins | 15 per second per vCPU |
| keycloak_credentials_password_hashing_validations_total | Password validations | 120 per second per vCPU |
| keycloak_user_events_total | Refresh token requests | 120 per second per vCPU |
Make sure to validate these metrics under load to confirm your server can handle the expected traffic.
Test Server Limits
Before deploying, test your Keycloak setup under stress using the Keycloak Benchmark repository. Here’s what has been validated for different operations:
| Operation Type | Maximum Tested Load |
|---|---|
| Password Logins | 300 per second |
| Client Credential Grants | 2,000 per second |
| Refresh Token Requests | 435 per second |
Once testing is complete, measure response times to ensure the system meets your performance goals.
Measure Speed and Resource Usage
Check that your system performs well during peak loads. Focus on response times, memory usage (heap and non-heap), and CPU allocation. For CPU, aim to:
- Maintain 150% extra capacity.
- Increase cache sizes if you have more than 2,500 concurrent clients.
- Regularly monitor daily and weekly load variations to adjust resources as needed.
Finally, use the Keycloak Benchmark observability stack in production to keep tracking performance. For more details on resource allocation, refer to Section 5: System Resources.
Conclusion
Optimizing Keycloak requires a mix of strategies to ensure it performs well under demanding conditions. Here’s a quick breakdown of the key steps:
- Resource Allocation:
- Plan for CPU capacity to be 150% above baseline needs, aiming for 1 vCPU per 15 login requests.
- Allocate 1,250 MB of memory per Keycloak pod, with 70% reserved for heap usage.
- Database Optimization:
- Set up 1,400 Write IOPS on Aurora PostgreSQL for every 100 login/logout/refresh requests.
- Use appropriate cache scaling ratios when managing over 2,500 concurrent clients.
- Cache Management:
- Limit Infinispan cache memory to avoid crashes.
- Turn off preload and disable statistics to reduce CPU usage.
- Configure minimum session owners for multi-server setups.
For systems handling high loads, like 2,000 client credential grants per second compared to 300 password-based logins, you may need to adjust these configurations.
Monitoring and Adjustments
Use Keycloak’s built-in tools to track performance metrics. Regularly test your system under peak conditions, update configurations as needed, and keep all components up to date. This will help maintain alignment with your workload demands.