Chapter 15. Configuring providers

Providers can be configured by using a specific configuration format. The format consists of:

spi-<spi-id>-<provider-id>-<property>=<value>

spi-<spi-id>-<provider-id>-<property>=<value>

The <spi-id> is the name of the SPI you want to configure.

The <provider-id> is the id of the provider you want to configure. This is the id set to the corresponding provider factory implementation.

The <property> is the actual name of the property you want to set for a given provider.

All those names (for spi, provider, and property) should be in lower case and if the name is in camel-case such as myKeycloakProvider, it should include dashes (-) before upper-case letters as follows: my-keycloak-provider.

Taking the HttpClientSpi SPI as an example, the name of the SPI is connectionsHttpClient and one of the provider implementations available is named default. In order to set the connectionPoolSize property you would use a configuration option as follows:

spi-connections-http-client-default-connection-pool-size=10

spi-connections-http-client-default-connection-pool-size=10

Provider configuration options are provided when starting the server. See all support configuration sources and formats for options in Configuring Red Hat build of Keycloak. For example via a command line option:

bin/kc.[sh|bat] start --spi-connections-http-client-default-connection-pool-size=10

bin/kc.[sh|bat] start --spi-connections-http-client-default-connection-pool-size=10

Depending on the SPI, multiple provider implementations can co-exist but only one of them is going to be used at runtime. For these SPIs, a specific provider is the primary implementation that is going to be active and used at runtime.

To configure a provider as the single provider you should run the build command as follows:

bin/kc.[sh|bat] build --spi-email-template-provider=mycustomprovider

bin/kc.[sh|bat] build --spi-email-template-provider=mycustomprovider

Depending on the SPI, multiple provider implementations can co-exist and one is used by default. For these SPIs, a specific provider is the default implementation that is going to selected unless a specific provider is requested.

The following logic is used to determine the default provider:

To configure a provider as the default provider you should run the build command as follows:

bin/kc.[sh|bat] build --spi-password-hashing-provider-default=mycustomprovider

bin/kc.[sh|bat] build --spi-password-hashing-provider-default=mycustomprovider

To enable or disable a provider you should run the build command as follows:

bin/kc.[sh|bat] build --spi-email-template-mycustomprovider-enabled=true

bin/kc.[sh|bat] build --spi-email-template-mycustomprovider-enabled=true

To disable a provider, use the same command and set the enabled property to false.

Custom providers should be packaged in a Java Archive (JAR) file and copied to the providers directory of the distribution. After that, you must run the build command in order to update the server’s provider registry with the implementations from the JAR file.

This step is needed in order to optimize the server runtime so that all providers are known ahead-of-time rather than discovered only when starting the server or at runtime.

To uninstall a provider, you should remove the JAR file from the providers directory and run the build command again.

When implementing a provider you might need to use some third-party dependency that is not available from the server distribution.

In this case, you should copy any additional dependency to the providers directory and run the build command. Once you do that, the server is going to make these additional dependencies available at runtime for any provider that depends on them.