Step-by-step integration of eXo Platform SSO via SAML2 with Keycloak

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.
eXo Platform SSO, SAML2, Keycloak

Content

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:
Integrate eXo Platform SOO via SAML2 with Keycloak
Now let’s get on with the step-by-step instructions.
eXo Platform 6 Free Datasheet​
Download the eXo Platform 6 Datasheet and
discover all the features and benefits
Download Now

Setting up Keycloak

First, launch and set up a Keycloak instance.
  1. Launch Keycloak (assuming that it would run on port 8080).
  2. Create ‘admin’ user and access to ‘administration console’.
Setting up Keycloak instance
  1. In Clients menu, add a new client.
# Referrer URI (in our case, we used eXo’s login service http://localhost:8090/portal/dologin).
  1. 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).
Export SAML Key
  1. Go to Settings, fill in the form as shown below and save.
Export SAML Key on localhost
  1. Go to Roles and add roles that already exist in eXo Platform (roles to use: users, administrators, web-contributors and guests, in lowercase).
Add Role SAML Key
  1. 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.
Add User SAML Key
For each user you create, add roles and assign credentials to them.
Root SAML Key

Setting up eXo Platform

The following assumes you have an eXo Platform instance running on localhost listening on port 8090. To learn how to do this, read the eXo Platform documentation.
  1. 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:
  1. Open the file $EXO_HOME/gatein/conf/exo.properties and add the following properties (add them if they do not exist):
				
					<pre class="lang:default decode:true ">gatein.sso.enabled=true
gatein.sso.callback.enabled=${gatein.sso.enabled}
gatein.sso.login.module.enabled=${gatein.sso.enabled}
gatein.sso.login.module.class=org.gatein.sso.agent.login.SAML2IntegrationLoginModule
gatein.sso.filter.login.sso.url=/@@portal.container.name@@/dologin
gatein.sso.filter.initiatelogin.enabled=false
gatein.sso.valve.enabled=true
gatein.sso.saml.config.file=$EXO_HOME/gatein/conf/saml2/picketlink-sp.xml
gatein.sso.idp.host=localhost
#Keycloak instance
gatein.sso.idp.url=http://${gatein.sso.idp.host}:8080/auth/realms/master/protocol/saml  
# eXo platform login URL
gatein.sso.sp.url=http://localhost:8090/portal/dologin 
# WARNING: This bundled keystore is only for testing purposes. You should generate and use your own keystore!
gatein.sso.picketlink.keystore=$EXO_HOME/gatein/conf/saml2/jbid_test_keystore.jks
gatein.sso.valve.class=org.gatein.sso.saml.plugin.valve.ServiceProviderAuthenticator
gatein.sso.filter.logout.enabled=false
gatein.sso.filter.initiatelogin.enabled=false
</pre>
  1. Copy the saml support libraries.

* Copy « jboss-security-spi-3.0.0.Final.jar » to $EXO_HOME/lib/

 

* Copy « sso-saml-plugin-5.2.2.jar » to $EXO_HOME/lib/ (For exo-saml 2.2.3 version, use « sso-saml-plugin-5.2.2.jar » )

 

** Edit the file $EXO_HOME/gatein/conf/saml2/picketlink-sp.xml  

 

# Add the appropriate KeyStorePass, SigningKeyPass and SigningKeyAlias passwords.

  1. 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.
Verify SAML Key
  1. 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).
  1. 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.
  1. 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.

 

SPOILER ALERT

 

* 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.

eXo Platform Digital Workplace
Connect your employees to their teams,
tools and information
Learn More
Rate this post
Jihed Chabbeh
Passionate for a long time by the new technologies, and more by the computer environment. I am particularly motivated by the relational aspect between the computer world of a company and its users: train, explain, configure, develop, maintain and troubleshoot.
Related posts
  • All
  • eXo
  • Digital workplace
  • Open source
  • Internal communication
  • Collaboration
  • News
  • intranet
  • Future of work
  • workplace
  • Knowledge management
  • Employee engagement
  • Employee experience
  • Employee productivity
  • onboarding
  • Employee recognition
  • Change management
  • Cartoon
  • Digital transformation
  • Infographic
  • Remote work
  • Tips & Tricks
  • Tutorial
  • Uncategorized

eXo Sneak Peek: navigation management and personalization

eXo Sneak Peek: navigation management and personalization This article is part of…
Read More
eXo

eXo Sneak Peek: multi-site management

eXo Sneak Peek: multi-site management This article is part of the “Sneak…
Read More
eXo

eXo launches its online community platform – eXo Tribe!

eXo launches its online community platform – eXo Tribe! We are excited…
Read More
eXo
Leave a Reply

( Your e-mail address will not be published)

guest
0 Comments
Commentaires en ligne
Afficher tous les commentaires