March 14, 2018

Drupal 8 and iMIS - A SAML Story

BCPhA and iMIS - A SAML Story
In the summer of 2017, Fuse started work on a new website for the BC Pharmacy Association (BCPhA). This new website was to be built in Drupal 8 and was part of BCPhA’s overhaul of their digital strategy. Among the various requirements of the build, was an integration with an existing third-party system BCPhA used to manage their members. This system had been in use by BCPhA for a while and their existing website integrated into this system.


iMIS, the third-party system, is a product offered by Advanced Solutions International who describe it as a “cloud-based engagement management system” that “fuses database management and web publishing”. For the purpose of the new BCPhA website, iMIS would function as an external user database and management system that needed to be integrated into Drupal. Users would need to be manageable from the iMIS backend, login using their username/email and password from iMIS, and pull their iMIS data into the website (including roles).

This integration needed to be seamless for the end user - not providing any unexpected roadblocks during their day to day use of the site. It also needed to integrate into Drupal in the most “Drupaly” way possible on the backend - as developers, we wanted to manage this integration, and the data we needed for our users, through existing Drupal methods and procedures.


After internal research and discussions, and discussions with the people at Visual Antidote, we landed on the solution of using a SAML protocol to handle this integration. SAML (Security Assertion Markup Language), in short, is an open standard for exchanging authentication details between two parties: an identity provider, or IDP, (which would be iMIS in our case) and a service provider, or SP (the Drupal site). The standard is well documented and supported which means that we wouldn’t have to reinvent the wheel, and many libraries and modules exist to support the integration. It works by sending a set of predetermined XML messages between the two parties along with redirects so a user can start on the Drupal site, be sent to an iMIS login page where they can securely authenticate, and then be returned to the Drupal site where they can automatically be logged in.

This means the final user experience of logging in and using the site can all appear seamless; unless the user is paying close attention, they won’t be aware they were just sent between two different websites to login. SAML additionally supports the ability to send user data along from the IDP to the SP when a user logs in, meaning everything needed for the Drupal site can be passed along and saved on the Drupal site in a normal, Drupal way. Lastly, but certainly not least, a SAML authentication approach was something that Visual Antidote (the iMIS consultant we worked with) was able to build and support.

Using SAML also provided a good layer of security to the integration, which is very important as we’re dealing with access to the site and user’s data. By being an open standard that’s been around for over 10 years, we can stand on the collective testing and knowledge of other developers that have built and have been using the standard in the wild. This provides much more confidence than if we were to build something entirely new and custom ourselves.


With all the items checked off our list of requirements for a potential integration, the next step was looking into integrating the SAML process into our new Drupal 8 based site, as well as integrating with the IDP that Visual Antidote was building for us to integrate with iMIS. Since the new site was being built in Drupal 8 we were a little limited in contributed modules that we could use for adding SAML support to the site. After looking at all the options, including developing a custom module ourselves to handle everything, we settled on the SAML Authentication contributed module. We chose this module as it didn’t require any large other libraries to be installed, was being actively developed, and supported everything we needed without too many modifications.

The SAML Authentication module essentially acts as a bridge between the OneLogin PHP SAML toolkit and Drupal, so it’s built on a solid foundation instead of trying to handle everything and remain secure on it’s own. It also provides events that a custom module can subscribe to to act on a user whenever they log in. These events allowed us to save user data that iMIS would be sending in the SAML response right onto the Drupal user (and even assign roles to the user based on role data that iMIS would send). To get logout functionality with this module, we did need to use the most recent development release, but no issues have arisen from it thus far.

There was a single, small problem with the module that we did run into. BCPhA had a requirement that on certain pages, if the user was directed to login they would return to the page they started on after they had successfully logged in. The SAML Authentication module seemingly supported this by including the url to return the user to in the destination parameter when they were directed to login, however that parameter is reserved by Drupal for other things. Simply changing the parameter to something else fixed the issue and enabled the functionality (a patch to fix the issue can be found here).



In the end we were very impressed with how this module worked in our integration. Because it was built with extensibility in mind, we didn’t have to make any major changes to the module at all and kept our custom functionality separate. Additionally, because it used the OneLogin PHP SAML library, we could easily test our integration and custom functionality by having OneLogin take the place of an IDP. This let us develop our end of things while the iMIS consultants developed their connector.

Our integration with the Visual Antidote built iMIS system itself was also very smooth. For two companies developing two systems in parallel that then have to communicate with each other and support users seamlessly, everything went extremely smoothly. Once both systems were finished, the final integration between the Drupal site and the iMIS system generated no major issues, only small tweaks.

The new BCPhA site has been up and running since November 21st 2017 and as of this writing has 2408 unique users that are logging in and using the site through the SAML integration with iMIS. Without a drop in service and minimal issues, the SAML functionality on the new site and the joint development of the implementation between Fuse and Visual Antidote has been a great success.

More information about Fuse's build of BCPhA's new site can be found here.