Features
Cluster Management

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.

Cluster Management Dashboard

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:

Cluster 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
  1. 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.

Cluster Detail Page

Click on any cluster from your clusters list to access the comprehensive cluster detail page. This page provides everything you need to manage your cluster in one place.

Cluster Detail Page

Admin Credentials & Console Access

The cluster detail page prominently displays your admin credentials and provides quick access to the Keycloak Admin Console:

  • Admin Username: Displayed in a read-only field with a copy button
  • Admin Password: Hidden by default with show/hide toggle and copy button
  • Open Admin Console: One-click button to launch your Keycloak Admin Console in a new tab

Security Note: These are your initial admin credentials. For security best practices, we recommend creating a separate admin account for daily use after your first login.

Detail Page Tabs

The cluster detail page is organized into tabs for easy navigation:

Overview Tab

  • Admin credentials section with copy-to-clipboard functionality
  • Cluster configuration (type, size, version, management mode)
  • Quick links to Security Settings, Logs, and Extensions

Realms Tab

  • View and manage all realms in your cluster
  • Access realm-specific settings and configurations

Security Tab

  • Configure security settings for your cluster
  • Manage firewalls and access controls

Theming Tab

  • Customize the look and feel of your login pages
  • Apply themes from the theme library

Extensions Tab

  • View and manage cluster extensions
  • Add custom functionality to your Keycloak instance

Settings Tab

  • Edit cluster name directly from this page
  • View cluster configuration details (location, type, size, version)
  • Access the Edit page for advanced configuration changes
  • Manage management mode, HTTP relative path, and other settings

Accessing the Keycloak Console

There are multiple ways to access your Keycloak Admin Console:

  1. From the Cluster Detail Page (Recommended):

    • Click on any cluster to open its detail page
    • Click the “Open Admin Console” button in the Admin Credentials section
    • Your credentials are displayed right there for easy reference

  2. From the Clusters List:

    • Find your cluster in the list
    • Click on the cluster card to open the detail page
    • Access the Admin Console from there

Accessing Cluster Logs

  1. Navigate to cluster detail page
  2. Click “View Logs” in the Quick Links section, or navigate to the Logs page
  3. View real-time logs and filter by cluster

Requesting Additional Features

From the cluster detail page, you can access:

  • Advanced security features (Security tab)
  • Custom domain setup (via Settings)
  • Custom theme implementation (Theming tab)
  • Extensions management (Extensions tab)

For specialized configurations not available in the dashboard, contact our support team.

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
  1. Click “Update” button
  2. 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.

Dashboard Overview