Keycloak-provider
Last updated
Last updated
In this module, you will find the Keycloak provider implementation.
Gazelle doesn't manage natively migration of realm configurations. As we need to maintain different instances of Gazelle in potential different versions of GUM. We need to be able to migrate realm configuration from one version of GUM to another.
To do this, we implemented our own migration system based on Keycloak client CLI.
For more information, see the .
If your users are not managed by Keycloak, you have to implement a user storage provider. For that you will need a factory and a provider.
In this project, our factory implements the UserStorageProviderFactory<GazelleUserStorageProvider>. In this class, we create the configuration metadata. For any service or DAO needed, we initiate them in the init method as this method called only once.
The getId method is used for the display of the provider name in the Keycloak administration console.
The user storage provider use the UserModel class that is a representation of a user in Keycloak. We create an adapter that extends the AbstractUserAdapterFederatedStorage class. In this adapter we use a model that is the representation from our point of view and map its attributes and methods to the adapter to make it compatible with keycloak.
If you need to do specific actions after an event is fired, you will need to implement a new Event Listener.
To do that you will need to create a factory and a provider.
It's possible to add an external identity provider to Keycloak. For that, you need to do it from the Keycloak administration console.
After you have added the identity provider, you can add a mapper to map the attributes from the external identity provider to the Keycloak user.
You can also customize some authentication flow with custom authenticators.
Finally, you can export the idp configurations as a JSON and save it in order to be able to create specific Keycloak migrations.
For authentication delegation, we implemented custom authenticators. These authenticators are added to the following authentication flow :
Browser : The authenticator call at each browser login
First broker login : The authenticator call at the first broker login
Reset credentials : The authenticator call at the reset credentials
Same for attribute mapping, there is custom available mappers. These mappers must be added manually to the identity provider.
We depend on other projects that need to following the Keycloak version :
Keycloak-protocol-cas : https://github.com/jacekkow/keycloak-protocol-cas
Keycloak-config-cli : https://github.com/adorsys/keycloak-config-cli
Keycloak-admin-client : (Integrated in Keycloak repo) : https://github.com/keycloak/keycloak/tree/main/js/libs/keycloak-admin-client
Keycloak-themes : (Integrated in Keycloak repo) : https://github.com/keycloak/keycloak/tree/main/themes
In order to upgrade Keycloak version used by the project, you must follow the following steps :
Update the keycloak.version property in the pom.xml file
Upload manually the released jar file in the nexus repository (https://nexus.ihe-europe.net/nexus/repository/maven-releases/)
Example of command executed to publish manually the jar file in the nexus repository :
For our custom themes, refresh the custom ftl page (login, reset-password, etc.) with the new version from keycloak-sources
To do that download the Keycloak jar
Open the tar.gz file and go to lib/lib/main/org.keycloak-admin-ui-$KEYCLOAK_VERSION.jar open it, open index.ftl and find imports It should look like this:
Update the based docker image in the Dockerfile of the keycloak-provider (FROM rg.fr-par.scw.cloud/tools/keycloak:${keycloak.version})
For the provider, you need to implement the UserStorageProvider interface and after you can implement other interfaces depending on your needs. For example implementing the UserLookupProvider interface will allow users outside keycloak to log in. For more information, see the.
For the factory, you should create a class that extends . This class implements EventListenerProviderFactory with empty methods. For your custom factory, you must at least override the create method, which will create your CustomEventListenerProvider, and the getId method, which must return a String that is the name displayed in Keycloak.
Then for the provider, you should create a class that extends . This class implements EventListenerProvider with two more methods to get the KeycloakSession and the RealmModel. These classes can be useful if you want to retrieve the user that fired the event. The provider has two onEvent methods, one for basic event (ex login, logout, login error, ...) and one for admin event, which are events fired in the administration console (ex create, delete, ...). Your provider should at least override one onEvent method.
Finally, do not forget to add your Event Factory in the file.
WARNING For the moment there is not protection mechanism to block external users. So the external idp are completely trusted. Avoid adding open idp like Google or Facebook where anyone can create an account. This would give access to Gazelle to anyone.
For more information, see the .
WARNING Upgrade Keycloak version is a critical operation. It must be done carefully and tested before being deployed in production.
Copy INDEX_ID and CSS_ID and replace them in the file