Shibboleth for Beginners — Part 1

Building a test service provider (SP)

After several years of running some hobby Ruby-on-Rails (RoR) apps using devise with database_authenticatable, I needed to add single-sign-on (SSO) capability via SAML and run my own identity provider (IdP). Enter Shibboleth — “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”. Unlike simple RoR apps, however, Shibboleth is a relatively complex Java web application (deployed with Jetty or Tomcat). It is a powerful implementation of SAML, includes back-end identity management options including JAAS, database, LDAP and Active Directory. Contributed flows include password-based authentication, multi-factor, and even OTP two-factor authentication (2FA).

Choose a Directory-as-a-Service (DaaS) provider

But first, I needed to experiment with the setup and see if it even worked before committing resources down this rabbit hole. I already had an idea for using the JumpCloud LDAP-as-a-service as identity store. LDAP is the default identity source for Shibboleth, but I did not want to configure OpenLDAP (another complex project) nor an Active Directory Domain Controller (ADDC). I also looked into JumpCloud alternatives, but found nothing as easy to experiment with for free. Here’s the list of services I evaluated:

• JumpCloud: 10 free users w/LDAP and SAML.
• Active Directory (on premise but exposed to Internet): has an LDAP interface but too expensive per user and difficult to secure on the open Internet.
• OpenLDAP: DIY … setup a server first on a VPS
• FoxPass: (product: Cloud LDAP) must have a G Suite or Office 365 account first.
• zFlex: (product: LDAP Cloud) … signup required first
• wso2 Cloud: IdP only — no LDAP-as-a-service. I used WSO2 Identity Server in a SAML experiment in the past, so I had one setup already. I also thought that the new WSO2 Cloud might provider LDAP-as-a-service, but not yet.
• Azure Active Directory Domain Services: DIY … LDAP, but with Microsoft twists and caveats.
• Okta: (product: Universal Directory) … signup required first.
• PingIdentity: (product: PingOne Directory) … signup required first.
• onelogin: (product: Virtual LDAP Service) … free account for SAML (3 service providers maximum) but signup required for LDAP-as-a-service.
• Centrify: (product: Centrify Identity Service) … signup required first.

As you can see, I didn’t want to yet engage sales contacts to get this experiment off the ground, so JumpCloud was the quickest path to solution. Indeed, their LDAP-as-a-service works pretty much as advertised.

A SAML Test Client

One of the other advantages of using JumpCloud is their support for SAML. You will now need to sign up for a free (10 user) JumpCloud account. Sign up for an administrator account. Once logged in, create a few fake users (select Users from the admin dashboard and click the + sign). I like to use the Simpsons characters like homer@example.com. Assign each a password when you create the user.

Localhost with JumpCloud SAML

You will first need to install git and Ruby-on-Rails (RoR) on your Windows, Mac or Linux box. You should also have a local instance of PostGres running as well. This is because you will deploy the application to Heroku in part 2. The instructions that follow were composed on a Mac running OS X 10.12.6 (Sierra). I used brew to install most of the tools I needed. Open up a bash terminal window and type the following commands to install the sample application from github:

% git clone https://github.com/johncallahan/rails-saml-sp.git
% cd rails-saml-sp
% bundle install

This will load all the gems needed for the application. Then,

% openssl genrsa -out idp.pem 2048
% openssl req -new -x509 -sha256 -key idp.pem -out idp.crt -days 365

This generates the public-private key pair (idp.pem is the private key and idp.crt is the associated certificate) based on these instructions. Just answer nothing for all the certificate questions (RETURN to accept the defaults). click APPLICATIONS on the dashboard menu.

Then, click the + sign to add a new application. You will see a long list of possible application templates. You are looking for the SAML template.

In the search box of the “Configure New Application” box, type “SAML”. Then, click Configure next to the SAML application that matches.

Fill the SAML application form as follows. You can use a different IDP Entity ID but you must be consistent throughout the form.

Click “Upload IdP Private Key” and select the idp.pem file you generated via the terminal window command before. Also, remember to use http not https when filling in the ACS URL. Then scroll up to complete the remainder of the form:

The suffix of the IDP URL and DISPLAY LABEL should be your IDP Entity ID you have used at the top of the form. Then click activate,

In this case, the IDP URL is https://sso.jumpcloud.com/saml2/exsaml001 (don’t try to click this link). You will need this in your environment variables below. Then, back to your terminal window:

% export ASSET_HOST=http://localhost:3000
% export ENTITY_ID=exsaml001
% export IDP_SSO_URL=https://sso.jumpcloud.com/saml2/exsaml001
% export IDP_SLO_URL=https://sso.jumpcloud.com/saml2/exsaml001
% export IDP_CERT="$(cat idp.crt)"
% rake db:create
% rake db:migrate

You should now be ready to start the Rails localhost web application. Type:

% rails s

and the result should show:

% rails s
=> Booting Puma
=> Rails 5.0.4 application starting in development on
=> Run `rails server -h` for more startup options
Puma starting in single mode...
* Version 3.9.1 (ruby 2.3.1-p112), codename: Private Caller
* Min threads: 5, max threads: 5
* Environment: development
* Listening on tcp://0.0.0.0:3000
Use Ctrl-C to stop

Then, open a browser and use a private window like in Firefox:

Type localhost:3000 in the URL box and hit RETURN. You should be redirected to the JumpCloud login page for your SAML endpoint (examine the URL box closely):

Type in the email and password of one of the users you created:

Then, you may see a warning because you are being redirected from an https address to an http address:

Then, you will be authenticated into the application! It’s just an empty list of products. Feel free to add some products.

You will need to close the private window to logout. Re-open a private window, navigate to http://localhost:3000/ again and watch SAML in action.

Conclusions

In Part 2, we will configure a Shibboleth IdP on Ubuntu 16.04. In Part 3, we will connect the Service Provider (SP) from Part 1 (this article) to the Shibboleth IdP from Part 2, and in Part 4, we will deploy the SP application to Heroku’s free tier.