[[_providers]] == Service Provider Interfaces (SPI) {project_name} is designed to cover most use-cases without requiring custom code, but we also want it to be customizable. To achieve this {project_name} has a number of Service Provider Interfaces (SPI) for which you can implement your own providers. [[_implementing_spi]] === Implementing an SPI To implement an SPI you need to implement its ProviderFactory and Provider interfaces. You also need to create a service configuration file. For example, to implement the Theme Selector SPI you need to implement ThemeSelectorProviderFactory and ThemeSelectorProvider and also provide the file `META-INF/services/org.keycloak.theme.ThemeSelectorProviderFactory`. Example ThemeSelectorProviderFactory: [source,java] ---- package org.acme.provider; import ... public class MyThemeSelectorProviderFactory implements ThemeSelectorProviderFactory { @Override public ThemeSelectorProvider create(KeycloakSession session) { return new MyThemeSelectorProvider(session); } @Override public void init(Config.Scope config) { } @Override public void postInit(KeycloakSessionFactory factory) { } @Override public void close() { } @Override public String getId() { return "myThemeSelector"; } } ---- NOTE: {project_name} creates a single instance of provider factories which makes it possible to store state for multiple requests. Provider instances are created by calling create on the factory for each request so these should be light-weight object. Example ThemeSelectorProvider: [source,java] ---- package org.acme.provider; import ... public class MyThemeSelectorProvider implements ThemeSelectorProvider { public MyThemeSelectorProvider(KeycloakSession session) { } @Override public String getThemeName(Theme.Type type) { return "my-theme"; } @Override public void close() { } } ---- Example service configuration file (`META-INF/services/org.keycloak.theme.ThemeSelectorProviderFactory`): [source] ---- org.acme.provider.MyThemeSelectorProviderFactory ---- ifeval::["{kc_dist}" == "quarkus"] You can configure your provider through server configuring. For example by adding starting the server with the following arguments: [source,bash] ---- bin/kc.[sh|bat] --spi-theme-selector-my-theme-selector-enabled=true --spi-theme-selector-my-theme-selector-theme=my-theme ---- endif::[] ifeval::["{kc_dist}" == "wildfly"] You can configure your provider through `standalone.xml`, `standalone-ha.xml`, or `domain.xml`. For example by adding the following to `standalone.xml`: [source,xml] ---- ---- endif::[] Then you can retrieve the config in the `ProviderFactory` init method: [source,java] ---- public void init(Config.Scope config) { String themeName = config.get("theme"); } ---- Your provider can also lookup other providers if needed. For example: [source,java] ---- public class MyThemeSelectorProvider implements ThemeSelectorProvider { private KeycloakSession session; public MyThemeSelectorProvider(KeycloakSession session) { this.session = session; } @Override public String getThemeName(Theme.Type type) { return session.getContext().getRealm().getLoginTheme(); } } ---- [[_providers_admin_console]] ==== Show info from your SPI implementation in the Admin Console Sometimes it is useful to show additional info about your Provider to a {project_name} administrator. You can show provider build time information (for example, 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). {project_name} 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: [source,java] ---- package org.acme.provider; import ... public class MyThemeSelectorProviderFactory implements ThemeSelectorProviderFactory, ServerInfoAwareProviderFactory { ... @Override public Map getOperationalInfo() { Map ret = new LinkedHashMap<>(); ret.put("theme-name", "my-theme"); return ret; } } ---- [[_use_available_providers]] === Use available providers In your provider implementation, you can use other providers available in {project_name}. The existing providers can be typically retrieved with the usage of the `KeycloakSession`, which is available to your provider as described in the section <<_implementing_spi,Implementing an SPI>>. {project_name} has two provider types: * *Single-implementation provider types* - There can be only a single active implementation of the particular provider type in {project_name} runtime. + For example `HostnameProvider` specifies the hostname to be used by {project_name} and that is shared for the whole {project_name} server. Hence there can be only single implementation of this provider active for the {project_name} server. If there are multiple provider implementations available to the server runtime, one of them needs to be specified as the default one. ifeval::["{kc_dist}" == "quarkus"] For example such as: [source,bash] ---- bin/kc.[sh|bat] build --spi-hostname-provider=default ---- endif::[] ifeval::["{kc_dist}" == "wildfly"] For example such as: [source,xml] ---- default ... ---- endif::[] The value `default` used as the value of `default-provider` must match the ID returned by the `ProviderFactory.getId()` of the particular provider factory implementation. In the code, you can obtain the provider such as `keycloakSession.getProvider(HostnameProvider.class)` * *Multiple implementation provider types* - Those are provider types, that allow multiple implementations available and working together in the {project_name} runtime. + For example `EventListener` provider allows to have multiple implementations available and registered, which means that particular event can be sent to all the listeners (jboss-logging, sysout etc). In the code, you can obtain a specified instance of the provider for example such as `session.getProvider(EventListener.class, "jboss-logging")` . You need to specify `provider_id` of the provider as the second argument as there can be multiple instances of this provider type as described above. + The provider ID must match the ID returned by the `ProviderFactory.getId()` of the particular provider factory implementation. Some provider types can be retrieved with the usage of `ComponentModel` as the second argument and some (for example `Authenticator`) even need to be retrieved with the usage of `KeycloakSessionFactory`. It is not recommended to implement your own providers this way as it may be deprecated in the future. ifeval::["{kc_dist}" == "quarkus"] === Registering provider implementations Providers are registered with the server by simply copying them to the `providers` directory. If your provider needs additional dependencies not already provided by Keycloak copy these to the `providers` directory. After registering new providers or dependencies Keycloak needs to be re-built with the `kc.[sh|bat] build` command. ==== Disabling a provider 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: [source,bash] ---- bin/kc.[sh|bat] build --spi-user-cache-infinispan-enabled=false ---- endif::[] ifeval::["{kc_dist}" == "wildfly"] === Registering provider implementations There are two ways to register provider implementations. In most cases the simplest way is to use the {project_name} deployer approach as this handles a number of dependencies automatically for you. It also supports hot deployment as well as re-deployment. The alternative approach is to deploy as a module. If you are creating a custom SPI you will need to deploy it as a module, otherwise we recommend using the {project_name} deployer approach. ==== Using the {project_name} deployer If you copy your provider jar to the {project_name} `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 {appserver_name} 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. ==== Register a provider using Modules .Procedure . Create a module using the jboss-cli script or manually create a folder. + .. For example, to add the event listener sysout example provider using the `jboss-cli` script, execute: + [source] ---- 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" ---- .. Alternatively, you can manually create the module inside `KEYCLOAK_HOME/modules` and add your jar and a `module.xml`. + For example, create the folder `KEYCLOAK_HOME/modules/org/acme/provider/main`. Then copy `provider.jar` to this folder and create `module.xml` with the following content: + [source,xml] ---- ---- . Register this module with {project_name} by editing the keycloak-server subsystem section of `standalone.xml`, `standalone-ha.xml`, or `domain.xml`, and adding it to the providers: + [source,xml] ---- auth module:org.keycloak.examples.event-sysout ... ---- ==== Disabling a provider 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: [source,xml] ---- ---- === Leveraging Jakarta EE The service providers can be packaged within any Jakarta EE component so long as you set up the `META-INF/services` file correctly to point to your providers. For example, if your provider needs to use third party libraries, you can package up your provider within an ear and store these third party libraries in the ear's `lib/` directory. Also note that provider jars can make use of the `jboss-deployment-structure.xml` file that EJBs, WARS, and EARs can use in a {appserver_name} environment. See the {appserver_name} documentation for more details on this file. It allows you to pull in external dependencies among other fine grain actions. `ProviderFactory` implementations are required to be plain java objects. But, we also currently support implementing provider classes as Stateful EJBs. This is how you would do it: [source,java] ---- @Stateful @Local(EjbExampleUserStorageProvider.class) public class EjbExampleUserStorageProvider implements UserStorageProvider, UserLookupProvider, UserRegistrationProvider, UserQueryProvider, CredentialInputUpdater, CredentialInputValidator, OnUserCache { @PersistenceContext protected EntityManager em; protected ComponentModel model; protected KeycloakSession session; public void setModel(ComponentModel model) { this.model = model; } public void setSession(KeycloakSession session) { this.session = session; } @Remove @Override public void close() { } ... } ---- You define the `@Local` annotation and specify your provider class there. If you don't do this, EJB will not proxy the provider instance correctly and your provider won't work. You put the `@Remove` annotation on the `close()` method of your provider. If you don't, the stateful bean will never be cleaned up and you may eventually see error messages. Ixmplementations of `ProviderFactory` are required to be plain java objects. Your factory class would perform a JNDI lookup of the Stateful EJB in its `create()` method. [source,java] ---- public class EjbExampleUserStorageProviderFactory implements UserStorageProviderFactory { @Override public EjbExampleUserStorageProvider create(KeycloakSession session, ComponentModel model) { try { InitialContext ctx = new InitialContext(); EjbExampleUserStorageProvider provider = (EjbExampleUserStorageProvider)ctx.lookup( "java:global/user-storage-jpa-example/" + EjbExampleUserStorageProvider.class.getSimpleName()); provider.setModel(model); provider.setSession(session); return provider; } catch (Exception e) { throw new RuntimeException(e); } } ---- endif::[] [[_script_providers]] === JavaScript providers {project_name} has the ability to execute scripts during runtime in order to allow administrators to customize specific functionalities: * Authenticator * JavaScript Policy * OpenID Connect Protocol Mapper ==== Authenticator 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. `script`:: the `ScriptModel` to access script metadata `realm`:: the `RealmModel` `user`:: the current `UserModel` `session`:: the active `KeycloakSession` `authenticationSession`:: the current `AuthenticationSessionModel` `httpRequest`:: the current `org.jboss.resteasy.spi.HttpRequest` `LOG`:: a `org.jboss.logging.Logger` scoped to `ScriptBasedAuthenticator` NOTE: You can extract additional context information from the `context` argument passed to the `authenticate(context)` `action(context)` function. [source,javascript] ---- 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(); } ---- ==== Create a JAR with the scripts to deploy NOTE: JAR files are regular ZIP files with a `.jar` extension. In order to make your scripts available to {project_name} you need to deploy them to the server. For that, you should create a `JAR` file with the following structure: [source] ---- 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: ```json { "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" } ] } ``` This file should reference the different types of script providers that you want to deploy: * `authenticators` + For OpenID Connect Script Authenticators. You can have one or multiple authenticators in the same JAR file + * `policies` + For JavaScript Policies when using {project_name} Authorization Services. You can have one or multiple policies in the same JAR file + * `mappers` + For OpenID Connect Script Protocol Mappers. You can have one or multiple mappers in the same JAR file 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: * `name` + A friendly name that will be used to show the scripts through the {project_name} Administration Console. If not provided, the name of the script file will be used instead + * `description` + An optional text that better describes the intend of the script file + * `fileName` + The name of the script file. This property is *mandatory* and should map to a file within the JAR. ==== Deploy the script JAR ifeval::["{kc_dist}" == "quarkus"] 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 {project_name} `providers/` directory, then run `bin/kc.[sh|bat] build`. endif::[] ifeval::["{kc_dist}" == "wildfly"] 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 {project_name} `standalone/deployments/` directory. endif::[] ===== Deploy the script engine on Java 15 and later To run the scripts, JavaScript providers require that a JavaScript engine is available in your Java application. Java 14 and lower versions include the Nashorn JavaScript Engine. It is automatically available as part of the Java itself and JavaScript providers are able to use this script engine by default. However, for Java 15 or higher versions, the script engine is not part of the Java itself. It needs to be added to your server because {project_name} does not have any script engine by default. Java 15 and higher versions require an extra step when deploying script providers - adding the script engine of your choice to your distribution. You can use any script engine. However, we only test with the Nashorn JavaScript Engine. The following steps assume that this engine is used: ifeval::["{kc_dist}" == "quarkus"] Install the script engine by copying the nashorn script engine JAR and its dependencies directly to the `KEYCLOAK_HOME/providers` directory. In the `pom.xml` file of your script project, you can declare the dependency such as this in the `dependencies` section: ```xml org.openjdk.nashorn nashorn-core 15.3 ``` and declare `maven-dependency-plugin` in the `plugins` section to copy the dependencies to the specified directory: ```xml org.apache.maven.plugins maven-dependency-plugin copy-dependencies-quarkus package copy-dependencies ${project.build.directory}/keycloak-server-copy/providers nashorn-core,asm,asm-util,asm-commons ``` Once the project is built, copy the script engine and its dependencies to the `KEYCLOAK_HOME/providers` directory. ```bash cp target/keycloak-server-copy/providers/*.jar KEYCLOAK_HOME/providers/ ``` After re-augment the distribution with `kc.sh build`, the script engine should be deployed and your script providers should work. endif::[] ifeval::["{kc_dist}" == "wildfly"] You can install the script engine by adding the new module nashorn-core to your {project_name}. After the server starts, you can run commands similar to these in the `KEYCLOAK_HOME/bin` directory: ```bash export NASHORN_VERSION=15.3 wget https://repo1.maven.org/maven2/org/openjdk/nashorn/nashorn-core/$NASHORN_VERSION/nashorn-core-$NASHORN_VERSION.jar ./jboss-cli.sh -c --command="module add --module-root-dir=../modules/system/layers/keycloak/ --name=org.openjdk.nashorn.nashorn-core --resources=./nashorn-core-$NASHORN_VERSION.jar --dependencies=asm.asm,jdk.dynalink" rm nashorn-core-$NASHORN_VERSION.jar ``` In case you want to install your provider into the different module, you can use configuration property `script-engine-module` of the default scripting provider. For example, you can use something such as this in your `KEYCLOAK_HOME/standalone/configuration/standalone-*.xml` file: ```xml ``` endif::[] ==== Using the {project_name} Admin Console to upload scripts NOTE: Ability to upload scripts through the Admin Console is deprecated and will be removed in a future version of {project_name}. Administrators cannot upload scripts to the server. This behavior prevents potential harm to the system in case malicious scripts are accidentally executed. Administrators should always deploy scripts directly to the server using a JAR file to prevent attacks when you run scripts at runtime. Ability to upload scripts can be explicitly enabled. This should be used with great care and plans should be created to deploy all scripts directly to the server as soon as possible. For more details about how to enable the `upload_scripts` feature, see link:{installguide_profile_link}[{installguide_profile_name}]. === Available SPIs If you want to see list of all available SPIs at runtime, you can check `Server Info` page in Admin Console as described in <<_providers_admin_console,Admin Console>> section.