Custom extensions on Cloud-IAM

Cloud-IAM Console - Custom Extension feature

What is custom extensions on Cloud-IAM

Keycloak is a powerful identity and access management solution designed to cover most common use cases right out of the box. However, there are situations where its default functionality may not fully address your unique business requirements. In these cases, custom extensions allow you to tailor and enhance Keycloak, bridging functionality gaps and adapting the platform precisely to your needs.

For a detailed overview of what custom extensions are, how they work, and best practices, please refer to our Custom Extensions Reference.

With Cloud-IAM managed Keycloak deployments, direct access to your Keycloak server for developing custom extensions is not available. Instead, all custom extension implementations must be processed through the Cloud-IAM Console or via the Cloud-IAM APIs.

What are the prerequisites to use the custom extension feature on Cloud-IAM?

Before managing custom extensions on Cloud-IAM, please ensure the following:

• Dedicated Keycloak Deployment: Custom extension support is available only on dedicated Keycloak deployments managed by Cloud-IAM.
• Support Plan: Your Cloud-IAM support plan must include the Custom Extension privilege, more details in Cloud-IAM pricing page.
• User Role: You must have the Editor role within your organization to upload, update, or delete custom extensions. For more details, see Organization Roles.
• Extension Packaging: Custom extensions must be packaged as Java .JAR files, compliant with Keycloak's Service Provider Interfaces (SPI).

How to upload your custom extension on Cloud-IAM console

You can upload your custom Keycloak extensions, packaged as Java .JAR files—directly through the Cloud-IAM Console. To perform this action, see Prerequisites to custom extension.

1. Open Cloud-IAM console
2. Select the Keycloak deployment where you want to upload the custom extension
3. Navigate on the Customisation section
4. Select Extensiontab
5. Click Upload
6. Select the .jar file containing your custom extension
7. Toggle the option to either apply immediately and trigger a restart or upload now and restart later.
8. Then click Upload to submit your extension

After 5–10 minutes, while your Keycloak deployment redeploys via the rolling upgrade process, the changes will be applied. Your custom extension is now uploaded to your deployment.

Cloud-IAM Console - Upload Custom Extension

How to upload your custom extension on Cloud-IAM APIs

You can upload your custom Keycloak extensions, packaged as Java .JAR files, directly using the Cloud-IAM API. This method is ideal for automating the deployment of custom extensions through your CI/CD pipelines.

Step 1 - Copy your deployment ID

To get started, you'll need your deployment ID.

1. Open Cloud-IAM console
2. Select the Keycloak deployment where you want to upload the custom extension
3. In the summary section, copy the Deployment ID.

Cloud-IAM Console - Get the deployment ID

Step 2 - Build and Execute the API

1. Build your custom extension (for the example extension is available in /home/user/projects/cloud-iam/extension/target/extension.jar)
2. Get token from service account
3. Indicate your token, deployment ID and the location on this command and execute it.

DEPLOYMENT_ID=xxxxx
curl -X POST -F extension=@/home/user/projects/cloud-iam/extension/target/extension.jar \
     -H "Authorization: Bearer $TOKEN" \
     https://api.cloud-iam.com/deployments/${DEPLOYMENT_ID}/extensions/jars

This will create a new resource attached to the deployment and will trigger automatically the deployment of the extension on the cluster.

During this period, no further interaction with the deployment are possible.

Batch the upload of multiple

If you need to batch the upload of multiple extension before re-deploying it, simply add ?apply=false at the end of the url to skip the automatic redeployment.

Once you are ready with the configuration / upload of extensions, call the following url to eventually apply all the changes.

DEPLOYMENT_ID=xxxxx
curl -X POST -H "Authorization: Bearer $TOKEN" \
     https://api.cloud-iam.com/deployments/${DEPLOYMENT_ID}/tasks/deploy

Requirement for legacy systems

A common requirement, especially when legacy systems are involved, is to integrate users from those systems into your Keycloak deployment. form 'extension=@example.jar'

$ curl --location --request POST 'https://api.cloud-iam.com/deployments/$DEPLOYMENT_ID/extensions/jars' \
       --header 'Authorization: Bearer $ACCESS_TOKEN' \
       --form 'extension=@example.jar'

How to update your custom extension on Cloud-IAM console

You can update your custom Keycloak extensions, packaged as Java .JAR files—directly through the Cloud-IAM Console. To perform this action, see Prerequisites to custom extension.

1. Open Cloud-IAM console
2. Select the Keycloak deployment where you want to update the custom extension
3. Navigate on the Customisation section
4. Select Extensiontab
5. Locate the custom extension you wish to update, click the ... menu next to it, then select Update
6. Select the .jar file containing your custom extension
7. Toggle the option to either apply immediately and trigger a restart or update now and restart later.
8. Then click Upload to submit the updated extension

After 5–10 minutes, while your Keycloak deployment redeploys via the rolling upgrade process, the changes will be applied. Your new version of the custom extension will replace the previous one on your deployment.

Cloud-IAM Console - Update Custom Extension

How to delete your custom extension on Cloud-IAM console

You can delete your custom Keycloak extensions, packaged as Java .JAR files—directly through the Cloud-IAM Console. To perform this action, see Prerequisites to custom extension.

1. Open Cloud-IAM console
2. Select the Keycloak deployment where you want to delete the custom extension
3. Navigate on the Customisation section
4. Select Extensiontab
5. Locate the custom extension you wish to delete, click the ... menu next to it, then select Delete
6. In the confirmation pop-up, choose whether to apply apply immediately and trigger a restart or Delete now and restart later.
7. Then click Remove to confirm and submit the deletion request.

After 5–10 minutes, while your Keycloak deployment redeploys via the rolling upgrade process, the changes will be applied. The custom extension has now been successfully removed from your deployment.

Cloud-IAM Console - Delete Custom Extension

Troubleshooting custom extension issue

Caused by: java.lang.ClassNotFoundException

If the extension relies on a Keycloak class, this can lead to an error during the start of the extension such as Caused by: java.lang.ClassNotFoundException: org.keycloak.services.managers.XXXXXX because on Quarkus the class loaders are isolated for safety reasons.

This issue can be resolved by declaring explicitly the dependencies needed by the extension in the MANFIEST.MF file.

If for instance, the extension's pom.xml contains such a dependency:

    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-services</artifactId>
        <scope>provided</scope>
        <version>${keycloak.version}</version>
    </dependency>

Then the following declaration must follow to tell Quarkus to share the classes between the server and the extension.

    <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-jar-plugin</artifactId>
       <configuration>
           <archive>
               <manifestEntries>
                   <Dependencies>org.keycloak.keycloak-services</Dependencies>
               </manifestEntries>
           </archive>
       </configuration>
    </plugin>