Cluster Management

The Cluster Management feature is the heart of Skycloak, allowing you to create and manage your Keycloak clusters efficiently. From here, you can view your clusters along with the amount of realms and users, access the Keycloak console, view logs, and request advanced features.

The cluster dashboard provides a comprehensive view of all your Keycloak instances, showing their status, location, version, size, and creation date.

Managing Clusters

Creating a New Cluster

1. Navigate to the Clusters page
2. Click “Create a Cluster” button
3. Configure your cluster using the creation wizard:

The wizard guides you through all the configuration options:

• Identity Platform: Choose between Keycloak or TideCloak
• Cluster Name: Give your cluster a descriptive name
• Keycloak Version: Select from the latest stable versions
• Cluster Size: Choose the right size for your environment:
  • Small (DEV) - 1 site: Ideal for development environments
  • Medium (STAGING) - 2 sites: Perfect for staging environments
  • Large (PROD) - 3 sites: Recommended for production environments
• Location: Select your preferred region (USA East Coast, Australia)
• Management Mode: Full Management or Semi-Managed

4. Click “Create Cluster” to start the provisioning process

Your cluster will be in “Creating” state for a few minutes, and you’ll receive an email notification when it’s ready. If it takes longer than 5 minutes, please contact us.

Accessing the Keycloak Console

1. From your clusters list, find the cluster you want to access
2. Click on the cluster card to view details
3. Click the “Go to Console” button to open your Keycloak administration console in a new tab

Cluster Details

Click on any cluster card to access the cluster details page:

• Cluster information
• Performance metrics
• Advanced features
• Logs access

Accessing Cluster Logs

1. Navigate to cluster details
2. Click “Request Logs” button
3. A request will be processed to gather your logs
4. You’ll receive an email within minutes containing your cluster’s Keycloak logs

Requesting Additional Features

From the cluster details page, you can request:

• Advanced security features (firewalls)
• Custom domain setup
• Custom theme implementation
• Other specialized configurations

Simply click the “Contact Us” button in the relevant section to submit your request.

Cluster Size Recommendations

When choosing a cluster size, consider your environment type and availability requirements:

Small Clusters (1 Site) - DEV Environment

• Best for: Development, testing, prototyping
• Characteristics: Single availability zone, no redundancy
• Use cases:
  • Development teams building applications
  • Testing new Keycloak features
  • Proof of concepts
  • CI/CD pipeline testing
• Availability: ~99.5% uptime (may have downtime during maintenance)

Medium Clusters (2 Sites) - STAGING Environment

• Best for: Staging, pre-production testing, UAT
• Characteristics: Multi-zone deployment, basic high availability
• Use cases:
  • Pre-production testing that mirrors production
  • User acceptance testing (UAT)
  • Performance testing
  • Integration testing with production-like setup
• Availability: ~99.9% uptime (survives single zone failures)

Large Clusters (3 Sites) - PRODUCTION Environment

• Best for: Production workloads requiring high availability
• Characteristics: Full multi-zone redundancy, maximum resilience
• Use cases:
  • Customer-facing production applications
  • Mission-critical authentication services
  • Enterprise applications
  • Applications requiring 24/7 availability
• Availability: ~99.99% uptime (survives multiple zone failures)

Cluster Operations

Updating a Cluster

1. Access cluster from dashboard or details page
2. Click “Edit” button
3. Choose new configuration options. You are currently limited to changing the cluster name and version.

Important Version Upgrade Notes:

• Version updates are only allowed to move forward (e.g., 21.0.1 to 21.0.2 or 21.1.0)
• Downgrading to a lower version is not possible due to database schema compatibility issues
• For major version upgrades, we recommend upgrading gradually through minor versions
• Use our Keycloak Upgrade Assistant GPT to help plan your version upgrade path

4. Click “Update” button
5. Your cluster will be updated within a few minutes and you will receive an email notification.

Deleting a Cluster

1. Access cluster dashboard or details page
2. Click the checkbox to give your consent to delete the cluster
3. Enter the name of the cluster to confirm deletion
4. Click “Schedule Deletion” button

Note: This will schedule the deletion of the cluster and you will receive an email notification when it’s done. For data protection purposes, we will keep your cluster’s data for 7 days before deleting it. You will be notified and warned days before deletion. Once deleted, any users from that cluster will be deleted along with the cluster.

You can also cancel the deletion of the cluster if you change your mind at any time before it’s deleted.

Advanced Keycloak Configuration

For users on Launch, Business, or Enterprise plans, Skycloak provides advanced Keycloak feature management. This allows you to enable or disable specific Keycloak features to customize your cluster’s behavior for advanced use cases.

Understanding Feature States

Keycloak features can exist in different states:

• Supported (Default Enabled): These features are production-ready and enabled by default in Keycloak. They work out-of-the-box and provide essential functionality that most users need.
• Supported (Default Disabled): Production-ready features that are disabled by default but can be safely enabled for production use.
• Preview: Features still in development that are not production-ready. While functional, preview features may have incomplete functionality, bugs, or breaking changes in future versions. Use with caution in production environments.
• Explicitly Enabled: Features that you have manually enabled for your cluster.
• Explicitly Disabled: Features that you have manually disabled for your cluster.

Accessing Feature Management

1. Navigate to your cluster’s edit page
2. Scroll down to find the “Advanced Keycloak Configuration” section
3. Click to expand the collapsible section
4. Browse features organized by category: Administration, Core Features, Integrations, Preview Features, Protocol Support, and Security

Supported Features (Production-Ready)

The following features are production-ready and can be safely used:

Default Enabled:

• Authorization Services: Fine-grained authorization support for complex permission scenarios
• WebAuthn: Modern FIDO2-based authentication support
• Admin REST API: Programmatic cluster management capabilities
• Client Policies: Define and enforce policies for client configurations
• Impersonation: Allow administrators to impersonate users for debugging
• Kerberos: Enterprise authentication integration
• Step-up Authentication: Enhanced authentication for sensitive operations
• Organizations (v26.0+): Multi-tenant organization management
• Persistent User Sessions (v25.0+): Store sessions in database for improved reliability
• OpenTelemetry (v24.0+): Distributed tracing for performance monitoring
• User Event Metrics (v24.0+): Collect metrics based on user events

Default Disabled (Can Be Enabled):

• FIPS 140-2 Mode (v21.0+): Federal compliance for government and regulated industries
• Docker Protocol: Container registry authentication support
• CIBA (v24.0+): Client Initiated Backchannel Authentication for mobile-first flows
• PAR (v22.0+): Pushed Authorization Requests for enhanced security
• Device Flow (v25.0+): OAuth 2.0 Device Authorization Grant

Preview Features (Not Production-Ready)

Warning: Preview features are still in development and should be used with caution in production environments. They may have incomplete functionality, bugs, or breaking changes in future versions.

The following features are currently in preview status across all supported Keycloak versions:

• Token Exchange: Exchange access tokens for different clients or realms (Dangerous: Security implications)
• Scripts: Write custom authenticators using JavaScript (Dangerous: Allows arbitrary code execution)
• DPoP (v23.0+): Demonstrating Proof of Possession for enhanced OAuth 2.0 security
• Recovery Codes: Backup codes for account recovery
• Passkeys (v22.0+): Passwordless authentication with passkeys (different from WebAuthn)
• Update Email: Allow users to update their email address with verification
• Admin Fine-Grained Authorization (v1): Detailed permission control for admin operations
• Client Secret Rotation: Automatic rotation of client secrets
• Declarative UI (v25.0+): Define custom UI extensions declaratively
• OID4VC (v25.0+): OpenID for Verifiable Credential Issuance
• Multi-Site (v26.0+): Active-active deployment across multiple geographic locations
• Transient Users (v24.0+): Temporary user accounts
• Declarative User Profile (v24.0+): Configure user profiles declaratively

Important Notes:

• Token Exchange has been in preview since Keycloak v4 and remains preview-only across all versions (20.x - 26.x)
• Admin Fine-Grained Authorization V2 (v25.0+) is the supported production-ready version
• Preview features marked as “Dangerous” have security implications and should be thoroughly tested

Managing Features

1. Viewing Features: All available features are displayed with their current state
2. Enabling Features: Click the checkbox next to a feature to enable it
3. Disabling Features: Click again to disable a feature (it will show as “Disabled”)
4. Applying Changes: Click “Apply Features” to save your configuration
5. Cluster Restart: Your cluster will automatically restart to apply the new feature configuration

Important: Changing features will restart your cluster, which may cause a brief interruption in service. Plan feature changes during maintenance windows.

Feature Versions

Some Keycloak features have multiple versions available with different capabilities. When a feature supports multiple versions, you’ll see a version dropdown selector next to the feature toggle.

Features with Multiple Versions

Feature	Versions	Default	Notes
admin-fine-grained-authz	v1, v2	v2	V1 is required for token exchange impersonation
login	v1, v2	v2	V1 is the deprecated legacy theme
rolling-updates	v1, v2	v1	V2 is preview with enhanced capabilities

How Version Selection Works

• Default Version: When you enable a feature without selecting a version, Keycloak uses the default version
• Non-Default Version: Select a different version from the dropdown to use that specific version
• Version Persistence: Your version selection is saved and applied when the cluster rebuilds

Token Exchange with Impersonation

To enable token exchange impersonation via a service account:

1. Enable the admin-fine-grained-authz feature
2. Select version V1 (required - V2 does not support impersonation)
3. Enable the token-exchange feature
4. Configure your service account with the appropriate permissions

Important: Admin Fine-Grained Authorization V2 is the production-ready default, but it does not support the impersonation permission required for token exchange. If you need token exchange impersonation, you must use V1.

Reference: Keycloak FGAP Documentation

Feature Compatibility

Features have different version availability:

• No minimum version: Available since Keycloak v20.0 or earlier
• Version-specific: Check version requirement (e.g., “v26.0+” means Keycloak 26.0.0 and later)
• Features marked “Incompatible” are not available in your current cluster version
• Upgrade your cluster version if needed to access certain features

Version Availability Examples:

• Token Exchange: Available since v20.0 (but remains preview)
• Organizations: Requires v26.0 or later
• Device Flow: Requires v25.0 or later
• FIPS Mode: Requires v21.0 or later

When to Use Feature Management

Feature management is particularly useful for:

• Security Compliance: Enable FIPS mode for government and regulated industry deployments
• Advanced Authentication: Enable supported features like WebAuthn for passwordless experiences
• Organization Management (v26.0+): Enable Organizations feature for multi-tenant architectures
• Session Reliability (v25.0+): Enable Persistent User Sessions for improved session management
• Development Testing: Enable preview features to test upcoming capabilities (non-production only)
• Performance Optimization: Disable unused features to optimize resource usage

Production Recommendation: Only enable Supported features in production environments. Preview features should be thoroughly tested in development/staging before considering production use.

Best Practices

1. Start with Defaults: Default supported features provide a solid foundation for most use cases
2. Use Supported Features in Production: Only enable preview features in development/staging environments
3. Enable Gradually: Add features one at a time to understand their impact
4. Test Thoroughly: Verify your applications work correctly after enabling new features
5. Document Changes: Keep track of which features you’ve enabled and why
6. Plan Restarts: Feature changes require cluster restarts - plan during maintenance windows
7. Review Preview Features: Monitor preview feature status across Keycloak versions - some remain preview for years
8. Be Cautious with “Dangerous” Features: Token exchange and scripts have security implications

Getting Help

If you need assistance with feature selection or configuration:

1. Contact our support team through the dashboard
2. Consult our integration guides for specific feature implementation
3. Check the Keycloak documentation for detailed feature descriptions

Note: Feature management is available on Launch, Business, and Enterprise plans. Trial users can preview the feature interface but cannot make changes until upgrading.