How to implement SAML SSO in Ruby with Sinatra

TLDR: Ruby (Sinatra) example app

Here’s an example app if you’d rather jump right in: https://github.com/ssoready/ssoready-example-app-ruby-sinatra-saml

SAML in Ruby (Sinatra): getting started

If you build software for a SaaS company – especially one that focuses on enterprise – you will eventually need to offer SAML single sign-on (SSO) to your customers.

But most developers have never really worked with SAML before. Most developers find the whole SAML thing very confusing. If you’re feeling similarly, that’s normal!

By the end of this guide, you should have a sense for how to set up a viable SAML implementation using Ruby. Note that this guide doesn’t cover Rails. We’ll put together a different guide at some point that gives a Rails example.

Okay, so what exactly is SAML?

Let’s start by understanding SAML in general. We won’t worry too much about the specifics of SAML + Ruby.

We at SSOReady put a few resources together that should help a bit:

A gentle introduction to SAML: Largely conceptual, this overview of SAML skips the details. You might find it useful if you’ve never dealt with SAML before.
SAML, a technical primer: This introduction to SAML lives a little deeper in the details. It’s also more practical. If you’re sure that you have to implement SAML, you should read this guide.

But I’ll assume you don’t want to read those.

SAML exists to help you log in your users (employees at a company) without requiring them to maintain credentials solely for your application. Your users instead present credentials to a centralized authentication service – called an identity provider – that your customer controls.

You’ll communicate with that identity provider using the SAML protocol, a standardized set of rules for passing security-related messages between systems. The identity provider will send you claims about users’ identities.

When you can confirm the authenticity and validity of the identity provider’s messages, you can proceed to let users access your application.

You might find the general outline of SAML a little confusing, but it’s really the details that’ll cause you trouble.

Should I be implementing SAML myself?

Unless you really, really know what you’re doing, you should not be implementing SAML yourself. You should be using a third-party service.

SAML’s not easy, and it can be really dangerous. It’s just a weird protocol that uses XML digital signatures, which invite all kinds of tricky problems. There are other subtle issues that might not be obvious, e.g. the multi-tenancy considerations that you’ll need to handle. SAML’s hard enough that we see major vulnerabilities crop up after years in widely-used SAML implementations.

More practically, SAML will eat up your time and attention. Getting something that works into production is a tall order. From there, someone needs to maintain the code over time. It’s hard to imagine many companies getting positive ROI from homegrown SAML implementations.

SSOReady Ruby SDK for SAML SSO

About SSOReady

We make SAML authentication tools for developers. If you need to support SAML single sign-on in your application, you can use us to abstract away all the hard stuff. We also have a few nice features that’ll improve your configuration experience.

We support all major programming languages and web frameworks. You can interface directly with our HTTP API using whatever tech stack you want. But we also make SDKs for common languages like Python, Javascript, Ruby, Java, C#, Go, and PHP. (For what it’s worth, if you need something else from us, send me a note at ned.oleary@ssoready.com).

All of our products are fully open source (MIT). We’re venture-funded, and we have real customers that rely on our services in production.

You can learn a bit more about us at ssoready.com.

SSOReady Ruby SDK

You can use our SAML middleware using our Ruby SDK (ssoready on RubyGems). The code’s actually pretty simple!

First, you have to install the gem.

gem install ssoready

You’ll need an API key. You can get one for free at app.ssoready.com.

From there, you can instantiate an SSOReady client like this:

require "ssoready"

ssoready = SSOReady::Client.new # loads your API key from the env var SSOREADY_API_KEY

You need an endpoint that redirects your app’s users back to their identity providers (for authentication). This endpoint doesn’t need to do much.

Here’s what it looks like:

# this is how you implement a "Sign in with SSO" button
redirect_url = ssoready.saml.get_saml_redirect_url(
    # the ID of the organization/workspace/team (whatever you call it)
    # you want to log the user into
    organization_external_id: "..."
).redirect_url

# redirect the user to `redirect_url`...

You’ll need a slightly more involved endpoint to process incoming SAML messages and authenticate users. It looks like this:

# this goes in your handler for POST /ssoready-callback
redeem_result = ssoready.saml.redeem_saml_access_code(saml_access_code: "saml_access_code_...")

email = redeem_result.email
organization_external_id = redeem_result.organization_external_id

# log the user in as `email` inside `organizationExternalId`...

Once you have those two endpoints in place, you’re pretty much done!

Please note that this isn’t the documentation. I’ve omitted a bunch of details in order to demonstrate some simplicity. Make sure you spend some time digging into our docs for SSOReady and checkout the GitHub for our Ruby SDK.

Ruby (Sinatra) SAML Example App

Get started with a Ruby (Sinatra) example app

We’ve written a maximally simple web application with Sinatra that supports SAML single sign-on.

There’s not even really a front-end. It’s pretty much just a single app.rb file that serves up static HTML.

You can run it right now:

git clone https://github.com/ssoready/ssoready-example-app-ruby-sinatra-saml
cd ssoready-example-app-ruby-sinatra-saml

bundle install
bundle exec ruby app.rb

More details live here. Notice that once you remove the comments, this is just a few lines of code! Pretty simple stuff.

Ruby SAML example app FAQs:

Where is the SAML authentication request?

We’ve abstracted this away for you. You don’t need to directly handle any XML. We log the SAML back-and-forth in our web app, which you can access at app.ssoready.com.

Where is the SAML response?

Just like with the request, We’ve abstracted away the SAML response for you. If you really want to look at it, check out app.ssoready.com.

What identity providers does SSOReady support?

Our app supports all SAML identity providers, including Microsoft Entra ID (formerly Azure AD), Okta, Shibboleth, and many others. We’ve written up some detailed instructions for different identity providers on our docs page.

Can I self-host SSOReady?

Yes, certainly! Check it the documentation here.

I have a problem. Can you help?

Of course. Please create an issue at https://github.com/ssoready/ssoready, and we’ll try to fix things for you. We just ask that you not create issues directly in the Ruby SDK repository – it’s a little easier for us to keep track if all issues live in the same place.

What are some other Ruby libraries I can use for SAML?

We’re definitely not your only option. There are a handful of alternatives that you might consider.

The most common open source library that we see is ruby-saml. Big companies use this in production. As I linked above, though, ruby-saml has had some issues. I wouldn’t advise relying too heavily on this library if you can help it.

Instructure has an open source project for handling SAML in Ruby. They’re a serious company – and I’d expect nearly all of their customers use SAML. I just haven’t run into any other companies that use their tool.

You might also have success using Keycloak. Fair warning: it has been my experience that most people have a hard time with Keycloak. It’s kind of a complicated and intricate tool. To be clear, I’m confident that it’ll work, but I can’t promise it’ll be easy.

If I’m missing any good ones, drop me an email at ned.oleary@ssoready.com.