Overview of Custom Providers with Keycloak
Out-of-the-box, Keycloak provides a range of standard-based integrations based on protocols like SAML, OpenID Connect, and OAuth2. While this built-in functionality is quite powerful, sometimes it's not enough. A common requirement, especially when legacy systems are involved, is to integrate users from those systems into Keycloak. To accommodate for this and similar integration scenarios, Keycloak supports the concept of custom providers.
Custom providers play a key role in Keycloak's architecture. For every major functionality, like the login flow, authentication, authorization, there's a corresponding Service Provider Interface. This approach allows us to plug custom implementations for any of those services, which Keycloak will then use as it were one of its own.
Available SPIs
Keycloak's main documentation lists the following SPIs:
org.keycloak.authentication.AuthenticatorFactory: Defines actions and interaction flows required to authenticate a user or client application
org.keycloak.authentication.actiontoken.ActionTokenHandlerFactory: Allows us to create custom actions that Keycloak will perform upon reaching the /auth/realms/master/login-actions/action-token endpoint. As an example, this mechanism is behind the standard password reset flow. The link included in the e-mail includes such an action token
org.keycloak.events.EventListenerProviderFactory: Creates a provider that listens for Keycloak events. The EventType Javadoc page contains a list of the available events custom a provider can handle. A typical use for using this SPI would be creating an audit database
org.keycloak.adapters.saml.RoleMappingsProvider: Maps SAML roles received from an external identity provider into Keycloak's ones. This mapping very flexible, allowing us to rename, remove, and/or add roles in the context of a given Realm
org.keycloak.storage.UserStorageProviderFactory: Allows Keycloak to access custom user stores
org.keycloak.vault.VaultProviderFactory: Allows us to use a custom vault to store Realm-specific secrets. Those can include information like encryption keys, database credentials, etc.
Now, this list by no means covers all the available SPIs: they're just the most well documented and, in practice, most likely to require customization
Sample SPI code can be found in https://github.com/dasniko/keycloak-user-spi-demoSteps to integrate
Step 1: Download the demo project available in git repo https://github.com/dasniko/keycloak-user-spi-demo
Step 2: Remove the unused hardcoded values from user repository class and write the connection code to query the users from database
Step 3: Have a jboss-deployment-structure.xml like the below code snippet
Module name is the package name of the userValidationProviderFactory
As provided https://stackoverflow.com/questions/46205475/keycloak-extension-with-dependencies
Step 4: If package names are renamed and restructured, the same should be changed in /keycloak-user-provider/src/main/resources/META-INF/services/org.keycloak.storage.UserStorageProviderFactory
Step 5: Add the lines in pom.xml to generate fat jar along with dependencies, this should be added inside <build> tag
Follow steps in http://tutorials.jenkov.com/maven/maven-build-fat-jar.html
Step 6: To configure plugin, include the following inside constructor of UserValidationProviderFactory
As provided in the link https://www.baeldung.com/java-keycloak-custom-user-providers
Step 7: To package the code run sh copy.sh or mvn clean package, once the command completes two jars are generated in the target folder. Rename the jar with dependencies as custom.jar and move it to the docker folder of the keycloak that needs to be run.
Ref: https://www.baeldung.com/java-keycloak-custom-user-providers
