Booked comes with multiple Single Sign On plugins out of the box. There are many benefits to SSO over standard authentication. For administrators, having a single point of account credential and access administration is very valuable. If someone leaves the organization they don’t have to deactivate accounts in multiple systems. For your normal user, the benefit is not having to register and remember yet another set of application credentials.

In this post we’ll cover how to set up SSO with SAML.

Most SSO configurations for Booked are pretty straightforward – you just update the configuration options for the plugin. But SAML is different. SAML requires a 3rd party application called SimpleSAMLphp to be running on the same server as Booked.

Install SimpleSAMLphp

Our first step is to download the latest version of SimpleSAMLphp and install it on your web server. I recommend installing it outside of your publicly visible directories and set up a subdomain pointing to the www directory.

For example, if you install it to /home/username/simplesamlphp and you have Booked running out of /home/username/public_html/booked, then you’d create a subdomain such as saml.bookedscheduler.com pointing to /home/username/simplesamlphp/www. The reason we do this is because the only files which need to be publicly visible in SimpleSAMLphp are located in the www directory. Exposing more than that opens unnecessary security holes.

Configure SimpleSAMLphp

SimpleSAMLphp has a lot of configuration options. If you’re like me and far from an expert in SAML, it’s overwhelming. Luckily, since Booked is a Service Provider it doesn’t need anything special.

I’ll go through each of the settings that need to be updated individually. Please note that at the time of writing this post, the latest version of SimpleSAMLphp was 1.18.5. It’s possible that the names of the options will change in future versions.

Open up home/username/simplesamlphp/config/config.php with a text editor.

baseurlpath should be updated to the full path of the SimpleSAMLphp www directory. If you followed the above advice and created a subdomain, this should be something like https://saml.yourdomain.com

technicalcontact_email should be set to your email address (or anyone responsible for managing SSO integrations)

secretsalt should be set to any secure, random value.

auth.adminpassword should be set to any secure, random value.

trusted.url.domains should be set to an array of domains that will participate in the SSO handshake. I use array(‘saml.bookedscheduler.com’, ‘bookedscheduler.com’)

session.cookie.domain should be set to the wildcard subdomain of your primary domain. For example, I use .bookedscheduler.com

session.cookie.secure should be set to true, assuming all traffic is sent over https.

store.type should be set to sql. This ensures that PHP sessions from Booked and sessions from SimpleSAMLphp do not conflict.

store.sql.dsn should be set to a writable location for the sqlite database. You must have SQLite support in PHP enabled for this to work. Alternatively, you can set up any PDO supported database to store session data. Since I use SQLite, I have this set to something like sqlite:/home/username/tmp/sqlitedatabase.sq3

Exchange Metadata

Now that we have the configuration set, we’ll need to exchange metadata.

The first thing to do is get the metadata XML from the Identity Provider that you’re integrating with. SimpleSAMLphp has a handy metadata XML conversion tool, which we’ll use to finish up our configuration.

Open the subdomain for SimpleSAMLphp in a browser (https://saml.bookedscheduler.com was what I used). Click on the Federation tab, then the XML to SimpleSAMLphp metadata converter link. You’ll be prompted to enter the auth.adminpassword that you set in your config.php

Paste in the XML or, if you have it saved to a file, upload it. SimpleSAMLphp will output at least one PHP version of that metadata.

For each one of those, location the file with the same name in /home/username/simplesamlphp/metadata. The most common files to update will be saml20-idp-remote.php or shib13-idp-remote.php

Delete everything except the opening php tag, then paste in the output from SimpleSAMLphp.

Copy the value of the entityid (usually found on the 3rd line of that file) and open up /simplesamlphp/config/authsources.php. Find the idp setting, and paste the value of the entityid there.

Update SAML Configuration in Booked

Whew, almost done. The last few settings are in Booked.

First, open up /your-booked-directory/config/config.php, find the authentication setting in the plugins section and set the value to Saml.

$conf['settings']['plugins']['Authentication'] = 'Saml';

Open up /your-booked-directory/plugins/Authentication/Saml and copy Saml.config.dist.php to Saml.config.php. Open Saml.config.php in an editor.

simplesamlphp.lib should be updated to the root filesystem directory of SimpleSAMLphp. If you’re using the settings I described here, this would be /home/username/simplesamlphp.

simplesamlphp.config should be updated to the config filesystem directory for SimpleSAMLphp. In this case /home/username/simplesamlphp/config

Most of the remaining settings are attribute maps. SAML will send over user attributes, but often with obscure names. Booked needs to know which attribute maps to the proper user field in Booked.

There are only 2 absolutely required fields to map – username/userid and email. For example, if the username is being sent across in the SAML payload as urn:oid:0.1.2.3 you’d set simplesamlphp.username to this value like $conf[‘settings’][‘simplesamlphp.username’] = ‘urn:oid:0.1.2.3’;

This is the same for all the other attributes. If you don’t know the attributes coming across then you can add the following line to plugins/Authentication/Saml/SamlUser.php as the first line in the constructor.

Log::Debug('Saml attributes are: %s', var_export($saml_attributes, true));

Enable Logging in Booked and try to log in. We’ll write out the attributes to the log file and you can copy the names into the Booked SAML configuration file.

Some Restrictions

A couple important notes with SAML enabled. The first is that you will no longer be able to log into Booked with any other credentials. There is no “back door” – so every authentication request will be routed through SAML.

The other restriction is that you will not be able to use any authenticated method from the API. SAML performs a series of browser redirects in order to complete the authentication process. When using the API you are not within the context of a browser, so authentication will fail.

Logging In

Once all the mapping is complete, you should be able to log into Booked via your organization’s federated log in page. Your users will no longer have to remember another set of credentials and your account management just got one step easier.