Chapter 5. Service Provider Interfaces (SPI)

As mentioned above, it is recommended that your ProviderFactory implementations use unique ID. However at the same time, it can be useful to override one of the Red Hat build of Keycloak built-in providers. The recommended way for this is still ProviderFactory implementation with unique ID and then for instance set the default provider as specified in the Configuring Providers chapter. On the other hand, this may not be always possible.

For instance when you need some customizations to default OpenID Connect protocol behaviour and you want to override default Red Hat build of Keycloak implementation of OIDCLoginProtocolFactory you need to preserve same providerId. As for example admin console, OIDC protocol well-known endpoint and various other things rely on the ID of the protocol factory being openid-connect.

For this case, it is highly recommended to implement method order() of your custom implementation and make sure that it has higher order than the built-in implementation.

public class CustomOIDCLoginProtocolFactory extends OIDCLoginProtocolFactory {

    // Some customizations here

    @Override
    public int order() {
        return 1;
    }
}

In case of multiple implementations with same provider ID, only the one with highest order will be used by Red Hat build of Keycloak runtime.

Sometimes it is useful to show additional info about your Provider to a Red Hat build of Keycloak administrator. You can show provider build time information (for example, version of custom provider currently installed), current configuration of the provider (e.g. 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 build of Keycloak 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 MyThemeSelectorProviderFactory implements ThemeSelectorProviderFactory, ServerInfoAwareProviderFactory {
    ...

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

You can disable a provider by setting the enabled attribute for the provider to false. For example to disable the Infinispan user cache provider use:

bin/kc.[sh|bat] build --spi-user-cache-infinispan-enabled=false

Authentication scripts must provide at least one of the following functions: authenticate(..), which is called from Authenticator#authenticate(AuthenticationFlowContext)action(..), which is called from Authenticator#action(AuthenticationFlowContext)

Custom Authenticator should at least provide the authenticate(..) function. You can use the javax.script.Bindings script within the code.

AuthenticationFlowError = Java.type("org.keycloak.authentication.AuthenticationFlowError");

function authenticate(context) {

  LOG.info(script.name + " --> trace auth for: " + user.username);

  if (   user.username === "tester"
      && user.getAttribute("someAttribute")
      && user.getAttribute("someAttribute").contains("someValue")) {

      context.failure(AuthenticationFlowError.INVALID_USER);
      return;
  }

  context.success();
}

- User-authentication-subflow REQUIRED
-- Cookie ALTERNATIVE
-- Identity-provider-redirect ALTERNATIVE
...
- Your-Script-Authenticator REQUIRED

OpenID Connect Protocol Mapper scripts are javascript script that allow you to change the content of the ID Token and/or the Access Token.

You can use the javax.script.Bindings script within the code.

The exports of the script will be used as the value of the token claim.

// prints can be used to log information for debug purpose.
print("STARTING CUSTOM MAPPER");

var inputRequest = keycloakSession.getContext().getHttpRequest();
var params = inputRequest.getDecodedFormParameters();
var output = params.getFirst("user_input");
exports = output;

The above script allows to retrieve a user_input from the authorization request. This will be available to map in the Token Claim Name configured in the mapper.

In order to make your scripts available to Red Hat build of Keycloak 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-script-authenticator.js",
            "description": "My Authenticator from a JS file"
        }
    ],
    "policies": [
        {
            "name": "My Policy",
            "fileName": "my-script-policy.js",
            "description": "My Policy from a JS file"
        }
    ],
    "mappers": [
        {
            "name": "My Mapper",
            "fileName": "my-script-mapper.js",
            "description": "My Mapper from a JS file"
        }
    ],
    "saml-mappers": [
        {
            "name": "My Mapper",
            "fileName": "my-script-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 need 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 Red Hat build of Keycloak providers/ directory, then run bin/kc.[sh|bat] build. Note that you also need to enable the scripts feature.