Marketplace - Migration from Custom Extensions
Overview
The Marketplace replaces the previous Customisation > Extensions page. Instead of managing custom extensions individually per deployment, the Marketplace centralizes extension management for your organization and provides a catalog of extensions developed by Cloud-IAM and the user community.
Key advantages of the Marketplace
Version management
Each extension in the Marketplace supports multiple releases. A release is tied to a specific JAR file and declares its compatibility with one or more Keycloak versions. This allows you to maintain and distribute different versions of the same extension for different Keycloak environments.
Centralized extension management
Extensions are now managed at the organization level rather than per deployment. A single extension can be installed on multiple deployments from one place, eliminating duplication and simplifying maintenance.
Technical validation
Every release goes through an automated validation process: the Marketplace starts a Keycloak instance with the extension to verify it loads correctly. Extensions that fail validation are flagged with a Failed status, with details available on hover. This prevents broken extensions from being deployed.
Migration from Custom Extensions to Marketplace
When the migration takes place, all existing custom extensions are automatically converted into Marketplace extensions. Here is what happens:
- A Marketplace extension is created for each custom extension, preserving its name and JAR file.
- A single release is created for the migrated extension, declared as compatible only with the Keycloak version currently running on the deployment where the custom extension was installed.
- If the same custom extension was installed on multiple deployments, a separate Marketplace extension is created for each instance. These may appear as duplicates.
After migration
Once migration is complete, all your extensions are available in the My Extensions page at the organization level. From there, you can:
- Merge duplicates: If the same extension was installed on several deployments, you now have multiple Marketplace extensions for it. You can consolidate them by keeping one and adding the necessary compatibility releases to cover all your Keycloak versions.
- Add new releases: For each extension, you can publish new releases targeting additional Keycloak versions by uploading updated JAR files and/or adjusting version compatibility.
- Monitor validation status: Each release shows its validation status (Validating, Validated, or Failed). Failed releases include a description of the issue.
Upgrade on-demand and extension compatibility
The Upgrade on-demand feature checks that all installed extensions are compatible with the target Keycloak version before allowing the upgrade to proceed.
How it works
When you trigger an upgrade on-demand for a deployment:
- The system verifies that every installed extension has at least one validated release declared as compatible with the target Keycloak version.
- If one or more extensions are not compatible, the upgrade is blocked.
What to do if the upgrade is blocked
To unblock the upgrade, go to the My Extensions page and for each incompatible extension:
- Add a new release with a JAR file compatible with the target Keycloak version, or
- Edit the compatibility of an existing release to include the target Keycloak version (if the JAR is already compatible but the version range was not declared).
Once all installed extensions have a validated release compatible with the target version, the upgrade on-demand can proceed.