Custom extensions on Keycloak ​

While Keycloak is designed to address most use cases out-of-the-box, there may be instances where its default functionality doesn't fully meet your specific requirements.

This is where custom extensions come in, allowing you to tailor Keycloak to your exact needs and bridge any gaps.

Definition of a custom extension on Keycloak ​

A custom extension in Keycloak refers to a customized implementation of a specific functionality or feature within the Keycloak platform. This can be achieved by creating a custom provider that plugs into one of Keycloak's Service Provider Interfaces (SPI).

Custom extensions allow you to modify or extend Keycloak's behavior, adding new features or modifying existing ones to suit your specific use case. These extensions can be implemented in Java and packaged as JAR files, which can then be deployed to a Keycloak instance.

Here are some examples of custom extensions that leverage Keycloak's Service Provider Interfaces (SPIs):

• Custom login flows: Implementing a custom login flow that integrates with an external authentication system.
• Custom authenticators: Creating a custom authenticator that verifies user credentials against an external source.
• Custom authorization providers: Implementing a custom authorization provider that checks user permissions against an external system.
• Custom theme implementations: Creating a custom theme for the Keycloak UI to match your organization's brand and style.

By creating custom extensions, you can tailor Keycloak to your specific needs, providing a high degree of customization and flexibility within the platform.

Implementing your custom extension on Cloud-IAM ​

Once you have subscribed to a paid plan (Little Bunny plan and above) Cloud-IAM allows you to integrate and deploy your custom extension on your Managed Keycloak.

To upload your custom extension, you have the following options.

Upload your custom extension via Cloud-IAM console ​

It is possible to upload your custom extension in Java and packaged as JAR files directly from the Cloud-IAM console. To proceed, you must benefit from the 'Editor' role, more information on the roles here.

1. Connect to Cloud IAM console
2. Select the deployment that should receive the custom extension
3. Scroll down to category 'Custom Extensions (jar)'
4. Click on Upload .jar file
5. Choose the .jar file to upload
6. Upload it

You have now uploaded your custom extension on your deployment.

Please note that it may take a few minutes for this import to be completely installed on your Keycloak deployment.

Upload your custom extension via Cloud-IAM API ​

It is possible to upload custom extensions through Cloud-IAM API to automatise it through your CI/CD pipelines.

Copy your deployment ID ​

1. Connect to Cloud IAM console
2. Select the deployment that should receive the custom extension
3. Extract your deployment ID by clicking on your deployment name (1.)

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

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.

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

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

$ curl --location --request POST 'https://api.cloud-iam.com/deployments/$DEPLOYMENT_ID/extensions/jars' \
       --header 'Authorization: Bearer $ACCESS_TOKEN' \
       --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' \

Update your custom extension on Cloud-IAM ​

Update your custom extension via Cloud-IAM console ​

It is possible to update your custom extension in Java and packaged as JAR files directly from the Cloud-IAM console. To proceed, you must benefit from the 'Editor' role, more information on the roles here.

1. Connect to Cloud IAM console
2. Select the deployment that should receive the custom extension
3. Scroll down to category 'Custom Extensions (jar)'
4. Click on Replace on the extension that you would like to update
5. Choose the .jar file to upload
6. Upload it

You have now uploaded your new version of custom extension on your deployment, the previous custom extension will be removed, and the new one will be uploaded.

Please note that it may take a few minutes for this update to be completely installed on your Keycloak deployment.

Delete your custom extension on Cloud-IAM ​

Delete your custom extension via Cloud-IAM console ​

It is possible to delete your custom extension, from the Cloud-IAM console. To proceed, you must benefit from the 'Editor' role, more information on the roles here.

1. Connect to Cloud IAM console
2. Select the deployment that should receive the custom extension
3. Scroll down to category 'Custom Extensions (jar)'
4. Click on Remove on the extension that you would like to delete

You have now deleted your custom extension on your deployment.

Please note that it may take a few minutes for this deletion to be completely done on your Keycloak deployment.

Troubleshooting ​

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>

<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>

<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>

Resources ​

• Keycloak documentation - Service Provider Interfaces (SPI)

• GitHub - Cloud-IAM theme