Chapter 6. Service Provider Interfaces (SPI)

Sometimes it is useful to show additional info about your Provider to a Red Hat Single Sign-On administrator. You can show provider build time information (eg. version of custom provider currently installed), current configuration of the provider (eg. url of remote system your provider talks to) or some operational info (average time of response from remote system your provider talks to). Red Hat Single Sign-On admin console provides Server Info page to show this kind of information.

To show info from your provider it is enough to implement org.keycloak.provider.ServerInfoAwareProviderFactory interface in your ProviderFactory.

Example implementation for MyThemeSelectorProviderFactory from previous example:

package org.acme.provider;

import ...

public class MyThemeSelectorProvider implements ThemeSelectorProvider, ServerInfoAwareProviderFactory {
    ...

    @Override
    public Map<String, String> getOperationalInfo() {
        Map<String, String> ret = new LinkedHashMap<>();
        ret.put("theme-name", "my-theme");
        return ret;
    }
}

If you copy your provider jar to the Red Hat Single Sign-On standalone/deployments/ directory, your provider will automatically be deployed. Hot deployment works too. Additionally, your provider jar works similarly to other components deployed in a JBoss EAP environment in that they can use facilities like the jboss-deployment-structure.xml file. This file allows you to set up dependencies on other components and load third-party jars and modules.

Provider jars can also be contained within other deployable units like EARs and WARs. Deploying with a EAR actually makes it really easy to use third party jars as you can just put these libraries in the EAR’s lib/ directory.

To register a provider using Modules first create a module. To do this you can either use the jboss-cli script or manually create a folder inside KEYCLOAK_HOME/modules and add your jar and a module.xml. For example to add the event listener sysout example provider using the jboss-cli script execute:

KEYCLOAK_HOME/bin/jboss-cli.sh --command="module add --name=org.acme.provider --resources=target/provider.jar --dependencies=org.keycloak.keycloak-core,org.keycloak.keycloak-server-spi"

Or to manually create it start by creating the folder KEYCLOAK_HOME/modules/org/acme/provider/main. Then copy provider.jar to this folder and create module.xml with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.3" name="org.acme.provider">
    <resources>
        <resource-root path="provider.jar"/>
    </resources>
    <dependencies>
        <module name="org.keycloak.keycloak-core"/>
        <module name="org.keycloak.keycloak-server-spi"/>
    </dependencies>
</module>

Once you’ve created the module you need to register this module with Red Hat Single Sign-On. This is done by editing the keycloak-server subsystem section of standalone.xml, standalone-ha.xml, or domain.xml, and adding it to the providers:

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
    <web-context>auth</web-context>
    <providers>
        <provider>module:org.keycloak.examples.event-sysout</provider>
    </providers>
    ...

You can disable a provider by setting the enabled attribute for the provider to false in standalone.xml, standalone-ha.xml, or domain.xml. For example to disable the Infinispan user cache provider add:

<spi name="userCache">
    <provider name="infinispan" enabled="false"/>
</spi>

In order to make your scripts available to Red Hat Single Sign-On you need to deploy them to the server. For that, you should create a JAR file with the following structure:

META-INF/keycloak-scripts.json

my-script-authenticator.js
my-script-policy.js
my-script-mapper.js

The META-INF/keycloak-scripts.json is a file descriptor that provides metadata information about the scripts you want to deploy. It is a JSON file with the following structure:

{
    "authenticators": [
        {
            "name": "My Authenticator",
            "fileName": "my-authenticator.js",
            "description": "My Authenticator from a JS file"
        }
    ],
    "policies": [
        {
            "name": "My Policy",
            "fileName": "my-policy.js",
            "description": "My Policy from a JS file"
        }
    ],
    "mappers": [
        {
            "name": "My Mapper",
            "fileName": "my-mapper.js",
            "description": "My Mapper from a JS file"
        }
    ]
}

This file should reference the different types of script providers that you want to deploy:

For each script file in your JAR file you must have a corresponding entry in META-INF/keycloak-scripts.json that maps your scripts files to a specific provider type. For that you should provide the following properties for each entry:

Once you have a JAR file with a descriptor and the scripts you want to deploy, you just need to copy the JAR to the to the Red Hat Single Sign-On standalone/deployments/ directory.

By default, the Red Hat Single Sign-On Administration Console won’t allow administrators to upload scripts to the server. The reason is that script execution can potentially harm the system due to the execution of malicious scripts. In order to prevent different types of attacks and lower the risks when running scripts at runtime, administrators should prefer deploying scripts directly to the server using a JAR file.

By deploying scripts directly into the server, we expect that scripts go through a proper code analysis in order to find possible vulnerabilities that can be introduced by any script deployed to the server.

However, it should still be possible to upload scripts to the server through the Red Hat Single Sign-On Administration Console. For that, you must set the following system property when booting the server:

    -Dkeycloak.profile.feature.upload_scripts=enabled

For more details about how to enable the upload_scripts feature. Please, take a look at the Profiles.