Liferay SSO - Step by Step

Integration with Keycloak

The landscape for Identity and Access Management has changed over the years. Whereas in the past, we'd often rely on proprietary or home grown solutions, we can now largely rely on well established standards.

Setting up Single Sign On has become easier as many SaaS providers offer some free plans and there is even easy-to-use software out there.

In this article, I'm going to show you how you can implement the two most popular SSO protocols: SAML and OpenID Connect.

For this, we need an Identity provider. In this demonstration we'll use Keycloakhttps://www.keycloak.org/downloads (use Keycloak server - Distribution powered by WildFly).

Setting up Keycloak

First thing, go update your hosts file (C:\Windows\System32\drivers\etc\hosts) and add a record to have an additional alias to the loopback address:

    127.0.0.1       sso

I always prefer to hit the ID Provider on a distinct host in order to avoid cookie collisions when I make local tests. If you are on a workstation where you don't have the rights to update your hosts, then I suggest you use 127.0.0.1 to hit Liferay and 127.0.0.2 (yes, it works!) to hit Keycloak so that they don't have the exact same hostname.

Now, unzip Keycloak server and edit this file: keycloak\standalone\configuration\standalone.xml

And update this line to include a 10000 port offset like this:

    <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:10000}">

You can now start Keycloak using this command: keycloak\bin\standalone.bat

Access Keycloak through this URL: http://sso:18080

You'll be offered to create an admin account. Proceed and access the administration console.

We'll now go to the Users section to add a test user:

Once you have created the user, you'll have to create some credentials:

We'll make that user's credentials permanent:


 

We now have a test user to sign in against Liferay.

Setting up OIDC on Liferay

First step is to register a new application in Keycloak. Go to the Clients section and click the create button on the top right:


 


 

You'll have to setup the liferay client as a confidential OIDC client (token negotiation is done on server side), don't forget to click the save button on the button and then fetch you client secret in the Credentials tab:


 

You'll need that client secret to configure Liferay:


 

In this example, I'm going to use Liferay DXP 7.3.

First visit the System settings to enable OIDC:


 

And now, let's create an OpenId Connect Provider. All the information you need can be fetched from here:


 

In Liferay, fill in those first fields, we'll leave the Discovery endpoint blank:


 

All the remaining information will be fetched from the OpenID Endpoint Configuration:



 

Now, open a new incognito window and try to sign in against Liferay and select OpenId Connect:

You'll get to choose that newly registered OIDC Endpoint:



Sign in against Keycloak:


 

And done:


 

If you were already signed in against Keycloak, then the Keycloak sign in page would be skipped.

Setting up SAML on Liferay

SAML integration works a bit differently in Liferay.

First thing to do, add a Sign In Widget to your home page so as to avoid trouble (getting locked outside).

Now enable SAML on Liferay, choose liferay-saml as your entity ID (because we used liferay for OIDC in Keycloak) and create the certificates:


 

You may now hit http://localhost:8080/c/portal/saml/metadata in order to retrieve the Liferay's SAML metadata.

Let's visit Keycloak and add a new SAML client (this is where you upload that saml metadata file):

Once the client is created, chance the NameID format to email (it means we are going to use email addresses as identifiers):

We'll now have to configure the SAML Mappers (how we translate user properties inside of the SAML assertion):



We'll create four of them:

Let's see them one by one:


To setup Liferay, you'll need the Keycloak IDP metadata file. You can get it here:

You'll find its entity ID in the XML file: 

Now let's go back to Liferay and configure the ID Provider connection:

Upload the IDP metadata file and fill in the form:


 

Be careful about Attribute Mapping. You're going to put the name of the Assertion attribute from the SAML message on the left (cf. the names we have configured in Keycloak) and Liferay's attribute names on the right hand side of the equal symbol.

Let's open a new incognito window and visit Liferay. Use the sign in button:


 

This time, you are sent straight away to Keycloak (that's why you better have your sign in portlet as a backup in case you did not get the SAML configuration right on your first attempt):



And done:


 

You now know how to setup Liferay against an IDP you can manage. This is very useful whenever you need to have a conversation with the IAM Administrators while setting up Liferay with the real IDP.