An OpenPaaS Story: Single Sign-On made easy with LemonLDAP

At Linagora, we are developing a lot of awesome open source software and the open collaborative platform OpenPaaS is one of those.

Now, OpenPaaS team started implementing single sign-on(SSO) for OpenPaaS. SSO is a form of access-control that connects multiple related, yet independent software systems like what we are having here in Linagora (OBM, LinShare,etc) by a single user database. Now OpenPaaS supports SSO by LemonLDAP as a external module.

Here I am going to talk about how we implemented Single Sign-on for OpenPaaS with LemonLDAP

An overview of how LemonLDAP works with OpenPaaS

LemonLDAP protects OpenPaaS behind a proxy, OpenPaaS then authenticates users by reading HTTP trusted-headers forwarded from LemonLDAP. See more about it here.

Let’s look at how the SSO flow looks when a user visits OpenPaaS :

  • User is redirected login page of LemonLDAP where they can log in.
  • LemonLDAP will check to see whether there is an existing SSO cookie.
  • If this is the first time the user visits this portal page, and no SSO cookie is presented, they need to be presented with username and password fields.
  • LemonLDAP will set a SSO cookie for first time login or update cookie otherwise.
  • LemonLDAP will prepare a SSO cookie for first time login or update cookie otherwise.
  • OpenPaaS gets the user information by reading the trusted-headers forwarded from LemonLDAP, converts it to OpenPaaS user. This information is then provisioned to OpenPaaS user database.

How

1. Install LemonLDAP::NG

First, you need to install LemonLDAP::NG software. Have a look here.

I will introduce how to install LemonLDAP::NG with Nginx on Debian in another article soon.

2. Install LemonLDAP awesome module

Clone the repository:

git clone https://ci.linagora.com/linagora/lgs/openpaas/linagora.esn.lemonldap.git

Go into the module directory and install module dependencies

npm install --production

3. Enable single sign-on for OpenPaaS

Next, you need to enable LemonLDAP awesome module for OpenPaaS. To do it, create a symbol link of this module in modules directory of OpenPaaS ESN:

ln -s path/to/linagora.esn.lemonldap /path/to/rse/modules

Then enable it in local configuration file:

“modules”: [
“linagora.esn.account”,

“linagora.esn.lemonldap” // add this line
]

Once enabled, this module will be loaded with OpenPaaS and ready to work.
The next step is to configure LemonLDAP virtualhost to protect OpenPaaS.

4. Configure LemonLDAP

To configure LemonLDAP, you must login to LemonLDAP manager page.

Add virtual host

LemonLDAP::NG configuration is built around Apache or Nginx virtual hosts. Each virtual host is a protected resource, with access rules, headers, POST data and options.

  • Have a look here to create virtual host in Apache/Nginx
  • In LemonLDAP Manager page, go to Virtual Hosts, click on Add virtualhost, then fill your Virtual host hostname.

Access Rule

In LemonLDAP Manager page, go to Virtual Hosts » <your virtualhost> » Access Rule,
click on New rule, then fill:

Commments: Protect home page
Regular expressions: ^/$
Rules: accept

In the same page, change the Default rule to unprotect to allow other resources of OpenPaaS to be accessible normally from outside.

5. Configure OpenPaaS

User provision

This module provisions users automatically on their first login. It converts the authenticated user information in trusted-headers to OpenPaaS user and creates a user instance on the storage layer (MongoDB). In the next logins, this module will perform re-provision to update user information if user has any change his information.

The converter needs a mapping to know which field in headers is corresponding to the user attribute in OpenPaaS. You can configure this mapping in global configuration.

The configuration is applied for the whole application so it must be platform-wide configuration, you can configure LemonLDAP mapping in Administrator module at platform mode.

6. Logout

What is Single Log Out?

LemonLDAP is a SSO, so, when you’re signed in, you can access to OpenPaaS and others apps, for example LinShare. When you logout from OpenPaaS, in fact you end your SSO session, so you also should logout from LinShare, …

Logout from OpenPaaS then LemonLDAP

In this case, OpenPaaS redirects the user to a logout endpoint of LemonLDAP after he logs out from OpenPaaS, hence the user is fully logged out from both services.

You can configure LemonLDAP logout endpoint in Administrator module at platform mode.

Logout from LemonLDAP then OpenPaaS

Once the user logs out from LemonLDAP, it then forwards the logout to other applications to close their sessions. LemonLDAP has a logout forward mechanism, that will add a step in logout process, to send logout requests (indeed, GET requests on application logout URL) inside hidden iframes.

In LemonLDAP Manager page, go to General parameters » Advanced parameters » Logout forward and click on Add a key, then fill:

Key: application name, e.g. OpenPaaS
Value: OpenPaaS logout URL, e.g. http://openpaas.yoursite.com/logout

Note that the request on logout URL will be sent after user is disconnected,
so you should unprotect this URL if it is protected by a LemonLDAP Handler.
Forturnately, this is done above by setting the Default rule to unprotect.

Result

The OpenPaaS Admin Team implemented the LemonLDAP logout and configuration in our latest sprint. Here is the demo video.

Conclusion

That is first step we achieved when implement SSO with OpenPaaS. In the next step, OpenPaaS team will deploy SSO on production with an already implemented LemonLDAP service for OBM system and hope it brings good experiences for users.

Keep in touch with us on Github, Twitter and don’t hesitate to apply to our jobs offers.

References