381 lines
13 KiB
Text
381 lines
13 KiB
Text
[[_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";
|
|
}
|
|
}
|
|
----
|
|
|
|
It is recommended that your provider factory implementation returns unique id by method `getId()`. However
|
|
there can be some exceptions to this rule as mentioned below in the <<_override_builtin_providers,Overriding providers>> section.
|
|
|
|
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
|
|
----
|
|
|
|
To configure your provider, see the link:https://www.keycloak.org/server/configuration-provider[Configuring Providers] guide.
|
|
|
|
For example, to configure a provider you can set options as follows:
|
|
|
|
[source,bash]
|
|
----
|
|
bin/kc.[sh|bat] --spi-theme-selector-my-theme-selector-enabled=true --spi-theme-selector-my-theme-selector-theme=my-theme
|
|
----
|
|
|
|
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 look up 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();
|
|
}
|
|
}
|
|
----
|
|
|
|
[[_override_builtin_providers]]
|
|
==== Override built-in providers
|
|
|
|
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 {project_name} 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 link:https://www.keycloak.org/server/configuration-provider[Configuring Providers] guide. 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 {project_name} 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.
|
|
|
|
[source,java]
|
|
----
|
|
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 {project_name} runtime.
|
|
|
|
[[_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 (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). {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<String, String> getOperationalInfo() {
|
|
Map<String, String> 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.
|
|
|
|
For example such as:
|
|
[source,bash]
|
|
----
|
|
bin/kc.[sh|bat] build --spi-hostname-provider=default
|
|
----
|
|
|
|
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.
|
|
|
|
=== 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
|
|
----
|
|
|
|
[[_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
|
|
* SAML 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"
|
|
}
|
|
],
|
|
"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:
|
|
|
|
* `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
|
|
+
|
|
* `saml-mappers`
|
|
+
|
|
For SAML 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
|
|
|
|
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`.
|
|
|
|
=== 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.
|