eXo Platform provides an implementation of single sign-on (SSO) as an integration and aggregation platform.
When logging into the portal, users gain access to many systems through portlets using a single identity. In many cases, the portal infrastructure must be integrated with other SSO-enabled systems.
There are many different identity management solutions available. In most cases, each SSO framework provides a unique way to plug into a Java EE application.
The following tutorial shows a step-by-step integration of eXo Platform SSO via SAML2 with Keycloak (using a basic configuration set-up).
Disclaimer: I am in no way an expert when it comes to SAML2 or Keycloak.
My idea and motive in writing this post was first to teach myself these concepts and also to give something back to the eXo community.
Although I have tried and tested all the steps myself, errors might have slipped in. If you spot anything fundamentally wrong with the information I have shared, please let me know. We are all continuously learning and we can certainly do that together.
I know your time is precious, so I have recorded a screencast with all the steps I described in this tutorial:
Now let’s get on with the step-by-step instructions.
Setting up Keycloak
First, launch and set up a Keycloak instance.
- Launch Keycloak (assuming that it would run on port 8080).
- Create ‘admin’ user and access to ‘administration console’.
- In Clients menu, add a new client.
# Referrer URI (in our case, we used eXo’s login service http://localhost:8090/portal/dologin).
- After saving, export the SAML key (and place it under folder gatein/conf/saml2): SAML KEYS → EXPORT: add a key and store password (to be filled in later in picketlink-sp.xml) and keep Realm Certificate Alias as it is (default value: master).
- Go to Settings, fill in the form as shown below and save.
- Go to Roles and add roles that already exist in eXo Platform (roles to use: users, administrators, web-contributors and guests, in lowercase).
- Go to Users > Add user and add users that already exist in eXo Platform (same usernames).
Note: Keycloak offers integration support for LDAP and Active Directory. You can also code your own extension for any custom user databases you might have using Keycloak’s User Storage SPI, otherwise you have to manually create users in Keycloak.
For more details, read Keycloak’s User Federation Storage Documentation.
For each user you create, add roles and assign credentials to them.
Setting up eXo Platform
- Install exo-saml-addon:
Note: We installed the exo-saml 2.2.2 version (add-on version compatible with eXo Platform 5.2.2). After installing the SAML2 add-on, its corresponding folder saml2 should be found under the path $EXO_HOME/standalone/configuration/gatein/. You need to move it under the path $EXO_HOME/gatein/conf by executing this command under $EXO_HOME path:
- Open the file $EXO_HOME/gatein/conf/exo.properties and add the following properties (add them if they do not exist):
- Copy the saml support libraries.
* Copy « jboss-security-spi-3.0.0.Final.jar » to $EXO_HOME/lib/
** Edit the file $EXO_HOME/gatein/conf/saml2/picketlink-sp.xml
# Add the appropriate KeyStorePass, SigningKeyPass and SigningKeyAlias passwords.
- Start eXo Platform:
Verifying everything works well
Now that you are all set, let’s make sure everything works as it should. I made another screencast for that too.
- Create some users in Keycloak and eXo Platform for testing. The username ‘john’ in eXo Platform must be the same as the username ‘john’ in Keycloak. Also, make sure the Keycloak users have the ‘users’ role (to access eXo Platform).
- Now, access eXo Platform. You will be redirected to the Keycloak login page. After you are authenticated with your Keycloak username, you will get access to eXo Platform.
- When you log out from eXo Platform, you should be redirected to the Keycloak login page.
In this article, we have shown you how to set up eXo Platform SSO via SAML2 with Keycloak.
This guide was made with:
eXo Platform: 5.2.2 / 5.2.3
Keycloak: 6.0.1 / 7.0.1
exo-saml: 2.2.2 / 2.2.3
Please share with us your experience in applying this tutorial to your own applications and contact us if you have any questions or issues.
* These steps will no longer be needed from eXo Platform 5.2.5 (being released soon).
** From eXo Platform 5.2.5, these properties will be set in exo.properties.