How to Integrate Enterprise Authentication with Keycloak — Part 1
Intro
Keycloak is an open-source software solution written in Java that enables single sign-on (IdP) through Identity Management and Access Management. It offers a broad range of integrations based on protocols such as SAML, OpenID Connect, and OAuth2. These features make Keycloak really flexible as well as solid. However, sometimes these features are not enough. Let’s imagine a scenario in which we have a legacy system combined with an ecosystem of new services; in turn, this legacy system is in charge of user authentication and authorization; so, how can we continue using this service without having to migrate all the users to Keycloak?
To simplify this sort of integrations, Keycloak introduces the concept of custom providers.
Keycloak and Custom Providers
A custom provider is a .jar file that contains one or more Service Provider Interface (SPI) implementations. There’s an SPI for each functionality, such as the login flow, authentication, or authorization. Thus, we’ll be able to provide implementations of those services, which the system will use as if they were its own.
At the startup phase, Keycloak scans the classpath to search for all the available providers through the Java ServiceLoader mechanism. Thus, for Keycloak to find our custom providers, we have to create a file named as the interface we’ll implement in the META-INF/services directory.
SPIs Implementation
The following is an example to show the SPIs implementation:
To perform the user authentication and authorization, Keycloak accesses our Legacy database on MySQL. Taking that into account, we’ll implement the org.keycloak.storage.UserStorageProviderFactory SPI, which allows Keycloak to access custom user stores. On Keycloak’s Server Info page within the Administration Console, you’ll find the full list of available SPIs.
Project Configuration
Ours is a Maven project that creates a .jar file, so we have to add keycloak-core and keycloak-server-spi as dependencies in the pom.xml file:
We also have to add the following properties:
Note: the infinispan.version and resteasy.version versions must match the versions configured on keycloak-parent effective pom.
UserStorageProviderFactory
In this implementation, we’ll focus on three methods:
- getId(): returns the identifier that Keycloak shows on the Server Info page.
- create(): returns the Provider implementation.
- init(): initializes the Provider Factory configuration.
Bear in mind that Keycloak invokes the create() method for each transaction that requires access to the user store. Thus, we should avoid costly initializations at this stage.
The new provider is named legacy-user-provider and the only thing left is to create the service definition file in META-INF/services under the following name: org.keycloak.storage.UserStorageProviderFactory. Its content will be the name of the SPI implementation:
LegacyUserStorageProvider
Keycloak expects our custom provider to implement mix-in interfaces that support particular aspects of user management. These interfaces are called Provider Capabilities. In our LegacyUserStorageProvider, we’ll implement:
UserStorageProvider
It contains a set of methods with default implementations, used as callback.
UserLookupProvider
It is used to recover a UserModel instance through its ID, username, or email.
CredentialInputValidator
It is used to validate the user credentials. In our case, the password is that credential.
UserQueryProvider
Although this is an optional interface, it’s advisable to implement it in order to see and manage users in the Administration Console. Among its most important methods, we can find:
Deployment
Manual Deployment
After creating the .jar file with Maven, we have to copy it here:
Next, we create a file with the same jar name and the dodeploy extension:
Finally, we start/restart Keycloak. If the jar deployment is successful, the .dodeploy file will turn into .deployed:
WildFly
The generated jar can be deployed using the WildFly Administration Console where Keycloak is already deployed:
Test
Once we’ve created the realm and client we’ll use on Keycloak, we set up the new provider in the Administration Console. Within our realm, select User Federation and the Add provider option where you’ll see all available providers are listed.
Once we’ve saved the changes, we can test the authentication of a user from the Legacy database through Keycloak’s REST API:
Conclusion
So far, we’ve learned that Keycloak is a powerful and versatile tool to manage access and user identity with a wide range of options to integrate into standard protocols as well as our own implementations. In addition, since it’s an open-source tool, it provides clarity to its implementation and examples to use its different features or to extend its functionalities.
Stay tuned for the second part of this article, in which we’ll learn how to integrate a web application into Keycloak’s login flow in a customized way. We’ll also integrate a REST API to validate user credentials, thus completing the example proposed in this article.
You can check everything we’ve worked on throughout this article in this GitHub repository.
Till next time!
