This post is a conceptual overview of implementing SSO with Shibboleth in Drupal 8. These concepts are going to be relevant if you are building a Drupal 8 site, and you have to allow thousands of authenticated users access to your site, without having to provision those user accounts ahead of time. Building and implementing a system using these parts involves several different pieces and, in my experience, it was a difficult at first to see the forest for the trees. Because SSO solutions can be built in many different ways, there is not a lot of documentation on the whole of the process. The goal of this post is to fill that gap, and I hope after reading this post you will come away with a better conceptual understanding of whatever task brought you to this post in the first place.
First off we need to define some terms:
SSO (Single Sign On): this is just a generic term for the concept. The concept is the idea of entering credentials (usually a password) in one place, and subsequently being able to access lots of other places.
Shibboleth: The Shibboleth website defines it as: “..an open-source project that provides Single Sign-On capabilities and allows sites to make informed authorization decisions for individual access of protected online resources in a privacy-preserving manner.” The rest of this post will expand on this.
SAML: The Wikipedia definition is concise: “Security Assertion Markup Language (SAML, pronounced sam-el) is an open standard for exchanging authentication and authorization data between parties…”
When I started the process of setting up SSO with Drupal the documentation I found was overly abstract and difficult to connect these concepts to anything I could hold on to. So to ground the concepts, I’m going to start by presenting an analogy. The point of this analogy is to drive home a key distinction that becomes the basis for understanding further ideas and how they relate.
Imagine, for a moment, that we’re going to a nightclub: Club Drupal. We get in the car and arrive at the club. Who do we see? Most nightclubs have two typical characters guarding the door: 1) A Bouncer, 2) A Clipboard keeper. The distinction between these roles will illustrate concepts important to SAML and SSO
Typically, the Bouncer just checks for a valid ID. He does not care if it’s a Driver’s license or passport. It could be a membership card, or an employment ID. All the Bouncer cares about about is whether it’s ok or not to let you in, based on certain criteria. (In the U.S., usually it is as simple as proving you are over age 18 or 21.)
Next, one typically talks to the the Clipboard Keeper. The Clipboard Keeper will then determine a level of access you get within the club (depending on the levels in the club). The Clipboard keeper will grant you access to general admission areas, reserved areas, VIP areas, or staff areas.
Bouncer <----> Identity Provider (IdP)
Clipboard Guy <-----> Service Provider (SP)
Keep in mind that both the Identity Provider and Service Provider are implementation agnostic, and SAML glues them together. What this means is the IdP and SP can be on the same server, or different servers. You can use Google as an IdP. You can use Facebook as an IdP. You can set up an OAuth IdP. You can use open source products to set up and run your own IdP and SP. Atlassian (maker of JIRA, Bitbucket, and Hipchat) can play the role of SP and can let you use your own IdP to let people in to your Atlassian account.
What is Shibboleth?
This brings us to Shibboleth. As mentioned at the start, it is an open source implementation of SSO via SAML. Basically, if you want to run and implement your own SSO system, Shibboleth is both an Identity Provider (IdP) and Service Provider (SP) that you can download, set up, and run as standalone services. It is open source and free, and heavily used by Universities and large organizations in the U.S. and Europe. The Shibboleth IdP can be hooked into an LDAP service, Kerberos, X.509, or other authentication services.
It's worth noting that you probably don't want to run a Shibboleth IdP if you don't have to (in my opinion.) As the IdP becomes the gatekeeper to your SSO network, a lot of care and thought should go into setting up and running an IdP securely. Both the Shibboleth IdP and SP are written in Java, so you'll need to know how to configure and run Java apps on either Apache or Tomcat. The server needs to be locked down and secured well. You will need to set up and manage key exchanges with your Service Providers, and you'll need to integrate the IdP with LDAP or some other credentialing system.
Shibboleth and Drupal 8
The good news is if you are just putting together a Drupal site that needs to allow users in by SSO, chances are someone else has set up and manages the IdP will authorize users. In this case, "integrating with Shibboleth" will mean allowing users that have authenticated with the Shibboleth IdP to gain access as authenticated users in your Drupal 8 site.
For Drupal 7, there were several Drupal modules that served both as a Service Provider (talking to the IdP) and granted access to your Drupal site. As of this writing, I could not find any that had been ported to Drupal 8.
It is not immediately obvious, but a good module to use to have Shibboleth provide authentication to a Drupal 8 site is Simplesamlphp_auth. I say "not immediately obvious" because the module works with Simplesamlphp which is a PHP implementation of SAML, and can work with other SAML SSO providers, not just Shibboleth.
So to get this working, you'll need to install and configure Simplesamlphp, which will serve as your Service Provider (SP). Configuring it will involve exchanging keys and metadata with the IdP. It has a nice web-based interface. A great feature of Simplesamlphp is that it provides a way for you to test getting authorized by your IdP and whether or not the trust relationship with the IdP is functioning correctly. I recommend making sure this works before proceeding to integrate with your Drupal site.
Once you've confirmed the trust relationship with your IdP is working, you can install and configure the simplesamlphp_auth module into your Drupal 8 site. The configuration options for the module in the Drupal admin allow you to fine tune the permissions within Drupal.
The diagram below shows how all the pieces fit together. I hope this article has provided a big-picture perspective on how these pieces fit together.
Build a Custom Drupal Site
Are you considering a partner in helping develop a custom Drupal website for your business? Contact us! We’re experts in delivering custom Drupal development for small businesses and large enterprises - and we’re eager to speak with you.
